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

package/README.md

@@ -137,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
@@ -147,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
@@ -166,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 |
@@ -179,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
 
@@ -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

@@ -137,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

package/index.ts

@@ -1,5 +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"
@@ -48,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) ---
@@ -125,6 +132,7 @@ export default {
           })
         }
 
+        track(EVENT_PLUGIN_STARTED, { project: cfg.project })
         log.info("connected — BM MCP stdio session running")
       },
       stop: async () => {

package/openclaw.plugin.json

@@ -48,8 +48,8 @@
     },
     "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": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basicmemory/openclaw-basic-memory",
-  "version": "0.1.0-alpha.8",
+  "version": "0.1.0-alpha.9",
   "type": "module",
   "description": "Basic Memory plugin for OpenClaw — local-first knowledge graph for agent memory",
   "license": "MIT",
@@ -9,6 +9,7 @@
     "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 ────────────────────────────────────────────────────────