@basicmemory/openclaw-basic-memory 0.1.0-alpha.2 → 0.1.0-alpha.9

package/README.md

@@ -55,6 +55,17 @@ If `uv` is not installed, the `bm` CLI setup is skipped gracefully during instal
 bash ~/.openclaw/extensions/openclaw-basic-memory/scripts/setup-bm.sh
 ```
 
+### Basic Memory Cloud
+
+Everything works locally — cloud adds cross-device, team, and production capabilities:
+
+- **Your agent's memory travels with you** — same knowledge graph on laptop, desktop, and hosted environments
+- **Team knowledge sharing** — org workspaces let multiple agents and team members build on a shared knowledge base
+- **Durable memory for production agents** — persistent memory that survives CI teardowns and container restarts
+- **Multi-agent coordination** — multiple agents can read and write to the same graph
+
+Cloud extends local-first — still plain markdown, still yours. Start with a [7-day free trial](https://basicmemory.com) and use code `BMCLAW` for 20% off for 3 months. See [BASIC_MEMORY.md](./BASIC_MEMORY.md) for cloud setup.
+
 ### Development (local directory)
 
 For plugin development, clone and link locally:
@@ -126,7 +137,7 @@ This installs to the same `skills/` directory the plugin reads from, so updated
 }
 ```
 
-This uses sensible defaults: auto-generated project name, maps Basic Memory to your workspace `memory/` directory, and captures conversations.
+This uses sensible defaults: auto-generated project name, maps Basic Memory to your workspace root, sets it as the default BM project, and captures conversations.
 
 ### Full configuration
 ```json5
@@ -136,7 +147,7 @@ This uses sensible defaults: auto-generated project name, maps Basic Memory to y
     config: {
       project: "my-agent",                          // BM project name (default: "openclaw-{hostname}")
       bmPath: "bm",                                 // Path to BM CLI binary
-      projectPath: "~/.openclaw/workspace/memory/",   // Optional override; supports absolute, ~/..., or workspace-relative paths
+      projectPath: ".",                                  // Defaults to workspace root; supports absolute, ~/..., or workspace-relative paths
       memoryDir: "memory/",                          // Relative memory dir for task scanning
       memoryFile: "MEMORY.md",                       // Working memory file for grep search
       autoCapture: true,                             // Index conversations automatically
@@ -155,7 +166,7 @@ This uses sensible defaults: auto-generated project name, maps Basic Memory to y
 |--------|------|---------|-------------|
 | `project` | string | `"openclaw-{hostname}"` | Basic Memory project name |
 | `bmPath` | string | `"bm"` | Path to Basic Memory CLI binary |
-| `projectPath` | string | `"memory/"` | Directory for BM project data (resolved from workspace unless absolute) |
+| `projectPath` | string | `"."` | Directory for BM project data (defaults to workspace root; resolved from workspace unless absolute) |
 | `memoryDir` | string | `"memory/"` | Relative path for task scanning |
 | `memoryFile` | string | `"MEMORY.md"` | Working memory file (grep-searched) |
 | `autoCapture` | boolean | `true` | Auto-index agent conversations |
@@ -168,7 +179,7 @@ Snake_case aliases (`memory_dir`, `memory_file`, `auto_recall`, `recall_prompt`,
 
 Cloud sync is optional — see [BASIC_MEMORY.md](./BASIC_MEMORY.md) for cloud configuration.
 
-On startup, the plugin ensures the configured BM project exists at `projectPath` via MCP `create_memory_project` in idempotent mode.
+On startup, the plugin ensures the configured BM project exists at `projectPath` via MCP `create_memory_project` in idempotent mode, and sets it as the default Basic Memory project.
 
 ## How It Works
 
@@ -287,17 +298,6 @@ After each agent turn (when `autoCapture: true`), the plugin:
 2. Appends them as timestamped entries to a daily conversation note (`conversations-YYYY-MM-DD`)
 3. Skips very short exchanges (< `captureMinChars` chars each, default 10)
 
-### Basic Memory Cloud
-
-Everything works locally — cloud adds cross-device, team, and production capabilities:
-
-- **Your agent's memory travels with you** — same knowledge graph on laptop, desktop, and hosted environments
-- **Team knowledge sharing** — org workspaces let multiple agents and team members build on a shared knowledge base
-- **Durable memory for production agents** — persistent memory that survives CI teardowns and container restarts
-- **Multi-agent coordination** — multiple agents can read and write to the same graph
-
-Cloud extends local-first — still plain markdown, still yours. Start with a [7-day free trial](https://basicmemory.com) and use code `BMCLAW` for 20% off for 3 months. See [BASIC_MEMORY.md](./BASIC_MEMORY.md) for setup, or visit [basicmemory.com](https://basicmemory.com) for more info.
-
 ## Agent Tools
 
 All content tools accept an optional `project` parameter to operate on a different project than the default (cross-project operations).
@@ -453,6 +453,17 @@ rm -rf /tmp/jiti/ "$TMPDIR/jiti/"
 openclaw gateway stop && openclaw gateway start
 ```
 
+### Disabling semantic search
+If you want to run without vector/embedding dependencies (faster startup, less memory), set the environment variable before launching:
+```bash
+BASIC_MEMORY_SEMANTIC_SEARCH_ENABLED=false
+```
+Or in `~/.basic-memory/config.json`:
+```json
+{ "semantic_search_enabled": false }
+```
+Search will fall back to full-text search only.
+
 ### Search returns no results
 1. Check that the MCP session is connected (look for `connected to BM MCP stdio` in logs)
 2. Verify files exist in the project directory
@@ -531,9 +542,7 @@ just release patch   # or: minor, major, 0.2.0, etc.
   4. publish to npm
   5. create a GitHub release
 
-Repository secret required:
-
-- `NPM_TOKEN` (npm publish token with package publish permissions)
+Publishing uses npm OIDC trusted publishing — no secrets required. The trusted publisher is configured on npmjs.com to accept provenance from this repo's `release.yml` workflow.
 
 ### Project Structure
 ```
@@ -564,6 +573,33 @@ openclaw-basic-memory/
     └── recall.ts         # Auto-recall (active tasks + recent activity)
 ```
 
+## Telemetry
+
+This plugin collects anonymous, minimal usage events to understand plugin adoption and tool usage patterns. This helps us prioritize features and improve the product.
+
+**What we collect:**
+- Plugin registration and startup events
+- First use of each tool per session (deduplicated — not every call)
+- Plugin version with each event
+
+**What we do NOT collect:**
+- No file contents, note titles, search queries, or conversation text
+- No personally identifiable information (PII)
+- No IP address tracking or fingerprinting
+- No per-command tracking beyond first-use-per-session
+
+Events are sent to our [Umami Cloud](https://umami.is) instance, an open-source, privacy-focused analytics platform. Events are fire-and-forget with a 3-second timeout — analytics never blocks or slows the plugin.
+
+**Opt out** by setting either environment variable:
+
+```bash
+# Plugin-specific opt-out
+export OPENCLAW_BASIC_MEMORY_TELEMETRY=0
+
+# Or use the shared Basic Memory opt-out (also disables BM CLI telemetry)
+export BASIC_MEMORY_NO_PROMOS=1
+```
+
 ## License
 
 MIT — see LICENSE file.

package/analytics.ts

@@ -0,0 +1,162 @@
+/**
+ * Lightweight analytics via Umami event collector.
+ *
+ * Sends anonymous, non-blocking usage events to help understand plugin adoption
+ * and tool usage patterns. No PII, no fingerprinting, no cookies.
+ *
+ * Events are fire-and-forget — analytics never blocks or breaks the plugin.
+ *
+ * Defaults point to the Basic Memory Umami Cloud instance. Override via:
+ *   BASIC_MEMORY_UMAMI_HOST     — Custom Umami instance URL
+ *   BASIC_MEMORY_UMAMI_SITE_ID  — Custom Website ID
+ * Opt out entirely with OPENCLAW_BASIC_MEMORY_TELEMETRY=0 or BASIC_MEMORY_NO_PROMOS=1.
+ */
+
+import { readFileSync } from "node:fs"
+import { join } from "node:path"
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+const DEFAULT_UMAMI_HOST = "https://cloud.umami.is"
+const DEFAULT_UMAMI_SITE_ID = "f6479898-ebaf-4e60-bce2-6dc60a3f6c5c"
+const SEND_TIMEOUT_MS = 3000
+
+function umamiHost(): string {
+  return process.env.BASIC_MEMORY_UMAMI_HOST?.trim() || DEFAULT_UMAMI_HOST
+}
+
+function umamiSiteId(): string {
+  return process.env.BASIC_MEMORY_UMAMI_SITE_ID?.trim() || DEFAULT_UMAMI_SITE_ID
+}
+
+export function analyticsDisabled(): boolean {
+  // Plugin-specific opt-out
+  const telemetry = (process.env.OPENCLAW_BASIC_MEMORY_TELEMETRY ?? "")
+    .trim()
+    .toLowerCase()
+  if (telemetry === "0" || telemetry === "false" || telemetry === "no") {
+    return true
+  }
+
+  // Shared Basic Memory opt-out (also disables BM CLI analytics)
+  const noPromos = (process.env.BASIC_MEMORY_NO_PROMOS ?? "")
+    .trim()
+    .toLowerCase()
+  return noPromos === "1" || noPromos === "true" || noPromos === "yes"
+}
+
+// ---------------------------------------------------------------------------
+// Version
+// ---------------------------------------------------------------------------
+
+let _cachedVersion: string | null = null
+
+function getVersion(): string {
+  if (_cachedVersion) return _cachedVersion
+  try {
+    const pkg = JSON.parse(
+      readFileSync(
+        join(import.meta.dirname ?? __dirname, "package.json"),
+        "utf-8",
+      ),
+    )
+    _cachedVersion = pkg.version ?? "unknown"
+  } catch {
+    _cachedVersion = "unknown"
+  }
+  return _cachedVersion ?? "unknown"
+}
+
+// ---------------------------------------------------------------------------
+// Session-scoped dedup for tool calls
+// ---------------------------------------------------------------------------
+
+const _trackedTools = new Set<string>()
+
+export function resetTrackedTools(): void {
+  _trackedTools.clear()
+}
+
+// ---------------------------------------------------------------------------
+// Event constants
+// ---------------------------------------------------------------------------
+
+export const EVENT_PLUGIN_INSTALLED = "openclaw-plugin-installed"
+export const EVENT_PLUGIN_STARTED = "openclaw-plugin-started"
+export const EVENT_TOOL_CALL = "openclaw-tool-call"
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Send an analytics event to Umami. Non-blocking, silent on failure.
+ *
+ * @param eventName - Short kebab-case name (e.g. "openclaw-plugin-started")
+ * @param data - Optional dict of event properties (string/number values)
+ */
+export function track(
+  eventName: string,
+  data?: Record<string, string | number>,
+): void {
+  if (analyticsDisabled()) return
+
+  const host = umamiHost()
+  const siteId = umamiSiteId()
+
+  const payload = {
+    payload: {
+      hostname: "openclaw.basicmemory.com",
+      language: "en",
+      url: `/openclaw/${eventName}`,
+      website: siteId,
+      name: eventName,
+      data: {
+        version: getVersion(),
+        ...(data ?? {}),
+      },
+    },
+  }
+
+  // Fire-and-forget — never block the plugin
+  _sendPayload(host, payload).catch(() => {})
+}
+
+/**
+ * Track a tool call, deduped per tool name per session.
+ * Only the first invocation of each tool sends an event.
+ */
+export function trackToolCall(toolName: string): void {
+  if (analyticsDisabled()) return
+  if (_trackedTools.has(toolName)) return
+  _trackedTools.add(toolName)
+  track(EVENT_TOOL_CALL, { tool: toolName })
+}
+
+// ---------------------------------------------------------------------------
+// Internal send (exported for testing)
+// ---------------------------------------------------------------------------
+
+export async function _sendPayload(
+  host: string,
+  payload: unknown,
+): Promise<void> {
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), SEND_TIMEOUT_MS)
+
+  try {
+    await fetch(`${host}/api/send`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "User-Agent": `openclaw-basic-memory/${getVersion()}`,
+      },
+      body: JSON.stringify(payload),
+      signal: controller.signal,
+    })
+  } finally {
+    clearTimeout(timer)
+  }
+}

package/bm-client.ts

@@ -1,6 +1,7 @@
 import { setTimeout as delay } from "node:timers/promises"
 import { Client } from "@modelcontextprotocol/sdk/client"
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"
+import { trackToolCall } from "./analytics.ts"
 import { log } from "./logger.ts"
 
 const DEFAULT_RETRY_DELAYS_MS = [500, 1000, 2000]
@@ -449,6 +450,7 @@ export class BmClient {
     name: string,
     args: Record<string, unknown>,
   ): Promise<unknown> {
+    trackToolCall(name)
     const result = await this.callToolRaw(name, args)
 
     if (!isRecord(result) || result.structuredContent === undefined) {

package/config.ts

@@ -6,6 +6,11 @@ export type CloudConfig = {
   api_key: string
 }
 
+export type DashboardConfig = {
+  enabled: boolean
+  port: number
+}
+
 export type BasicMemoryConfig = {
   project: string
   bmPath: string
@@ -18,6 +23,7 @@ export type BasicMemoryConfig = {
   recallPrompt: string
   debug: boolean
   cloud?: CloudConfig
+  dashboard: DashboardConfig
 }
 
 const ALLOWED_KEYS = [
@@ -37,6 +43,7 @@ const ALLOWED_KEYS = [
   "recall_prompt",
   "debug",
   "cloud",
+  "dashboard",
 ]
 
 function assertAllowedKeys(
@@ -106,6 +113,22 @@ export function parseConfig(raw: unknown): BasicMemoryConfig {
     }
   }
 
+  let dashboard: DashboardConfig = { enabled: false, port: 3838 }
+  if (
+    cfg.dashboard &&
+    typeof cfg.dashboard === "object" &&
+    !Array.isArray(cfg.dashboard)
+  ) {
+    const d = cfg.dashboard as Record<string, unknown>
+    dashboard = {
+      enabled: typeof d.enabled === "boolean" ? d.enabled : false,
+      port:
+        typeof d.port === "number" && d.port > 0 && d.port < 65536
+          ? d.port
+          : 3838,
+    }
+  }
+
   return {
     project:
       typeof cfg.project === "string" && cfg.project.length > 0
@@ -114,7 +137,7 @@ export function parseConfig(raw: unknown): BasicMemoryConfig {
     projectPath:
       typeof cfg.projectPath === "string" && cfg.projectPath.length > 0
         ? cfg.projectPath
-        : memoryDir,
+        : ".",
     bmPath:
       typeof cfg.bmPath === "string" && cfg.bmPath.length > 0
         ? cfg.bmPath
@@ -144,6 +167,7 @@ export function parseConfig(raw: unknown): BasicMemoryConfig {
           : "Check for active tasks and recent activity. Summarize anything relevant to the current session.",
     debug: typeof cfg.debug === "boolean" ? cfg.debug : false,
     cloud,
+    dashboard,
   }
 }
 

package/index.ts

@@ -1,4 +1,10 @@
+import type { Server } from "node:http"
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import {
+  EVENT_PLUGIN_INSTALLED,
+  EVENT_PLUGIN_STARTED,
+  track,
+} from "./analytics.ts"
 import { BmClient } from "./bm-client.ts"
 import { registerCli } from "./commands/cli.ts"
 import { registerSkillCommands } from "./commands/skills.ts"
@@ -8,6 +14,7 @@ import {
   parseConfig,
   resolveProjectPath,
 } from "./config.ts"
+import { createDashboardServer } from "./dashboard/server.ts"
 import { buildCaptureHandler } from "./hooks/capture.ts"
 import { buildRecallHandler } from "./hooks/recall.ts"
 import { initLogger, log } from "./logger.ts"
@@ -46,6 +53,8 @@ export default {
       `project=${cfg.project} memoryDir=${cfg.memoryDir} memoryFile=${cfg.memoryFile}`,
     )
 
+    track(EVENT_PLUGIN_INSTALLED)
+
     const client = new BmClient(cfg.bmPath, cfg.project)
 
     // --- BM Tools (always registered) ---
@@ -80,6 +89,8 @@ export default {
     registerCli(api, client, cfg)
 
     // --- Service lifecycle ---
+    let dashboardServer: Server | undefined
+
     api.registerService({
       id: "openclaw-basic-memory",
       start: async (ctx: { config?: unknown; workspaceDir?: string }) => {
@@ -108,10 +119,31 @@ export default {
 
         setWorkspaceDir(workspace)
 
+        // Start dashboard if enabled
+        if (cfg.dashboard.enabled) {
+          dashboardServer = createDashboardServer({
+            port: cfg.dashboard.port,
+            client,
+          })
+          dashboardServer.listen(cfg.dashboard.port, () => {
+            log.info(
+              `dashboard running at http://localhost:${cfg.dashboard.port}`,
+            )
+          })
+        }
+
+        track(EVENT_PLUGIN_STARTED, { project: cfg.project })
         log.info("connected — BM MCP stdio session running")
       },
       stop: async () => {
         log.info("stopping BM MCP session...")
+        if (dashboardServer) {
+          await new Promise<void>((resolve) =>
+            dashboardServer?.close(() => resolve()),
+          )
+          dashboardServer = undefined
+          log.info("dashboard stopped")
+        }
         await client.stop()
         log.info("stopped")
       },

package/openclaw.plugin.json

@@ -48,14 +48,19 @@
     },
     "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",
+      "placeholder": ".",
+      "help": "Filesystem path for Basic Memory project data (defaults to workspace root; relative paths resolve from workspace)",
       "advanced": true
     },
     "cloud": {
       "label": "Cloud Backend",
       "help": "Optional cloud backend config (url + api_key). If present, uses cloud instead of local BM.",
       "advanced": true
+    },
+    "dashboard": {
+      "label": "Dashboard",
+      "help": "Web dashboard for visualizing the knowledge graph (enabled, port)",
+      "advanced": true
     }
   },
   "configSchema": {
@@ -76,6 +81,13 @@
           "url": { "type": "string" },
           "api_key": { "type": "string" }
         }
+      },
+      "dashboard": {
+        "type": "object",
+        "properties": {
+          "enabled": { "type": "boolean" },
+          "port": { "type": "number", "minimum": 1, "maximum": 65535 }
+        }
       }
     },
     "required": []

package/package.json

@@ -1,10 +1,15 @@
 {
   "name": "@basicmemory/openclaw-basic-memory",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.9",
   "type": "module",
   "description": "Basic Memory plugin for OpenClaw — local-first knowledge graph for agent memory",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/basicmachines-co/openclaw-basic-memory"
+  },
   "files": [
+    "analytics.ts",
     "index.ts",
     "bm-client.ts",
     "config.ts",

package/scripts/setup-bm.sh

@@ -15,11 +15,10 @@ if ! command -v uv >/dev/null 2>&1; then
   exit 0
 fi
 
-# ── install basic-memory[semantic] ────────────────────────────────
+# ── install basic-memory ────────────────────────────────
 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"' \
+  "basic-memory @ git+${BM_REPO}@${BM_REF}" \
   --force
 
 # ── verify ────────────────────────────────────────────────────────