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

package/README.md

@@ -36,9 +36,6 @@ For a practical runbook, see [Memory + Task Flow](./MEMORY_TASK_FLOW.md).
 # Install the plugin (automatically installs the bm CLI via uv)
 openclaw plugins install @basicmemory/openclaw-basic-memory
 
-# Enable and assign to the memory slot
-openclaw plugins enable basic-memory --slot memory
-
 # Restart the gateway
 openclaw gateway restart
 ```
@@ -46,7 +43,7 @@ openclaw gateway restart
 Verify:
 ```bash
 openclaw plugins list
-openclaw plugins info basic-memory
+openclaw plugins info openclaw-basic-memory
 ```
 
 If `uv` is not installed, the `bm` CLI setup is skipped gracefully during install. Install `uv` first, then re-run the postinstall script:
@@ -55,6 +52,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:
@@ -64,7 +72,7 @@ git clone https://github.com/basicmachines-co/openclaw-basic-memory.git
 cd openclaw-basic-memory
 bun install
 openclaw plugins install -l "$PWD"
-openclaw plugins enable basic-memory --slot memory
+openclaw plugins enable openclaw-basic-memory --slot memory
 openclaw gateway restart
 ```
 
@@ -77,12 +85,12 @@ Or load directly from a path in your OpenClaw config:
       paths: ["~/dev/openclaw-basic-memory"]
     },
     entries: {
-      "basic-memory": {
+      "openclaw-basic-memory": {
         enabled: true
       }
     },
     slots: {
-      memory: "basic-memory"
+      memory: "openclaw-basic-memory"
     }
   }
 }
@@ -120,23 +128,23 @@ This installs to the same `skills/` directory the plugin reads from, so updated
 ### Minimal (zero-config)
 ```json5
 {
-  "basic-memory": {
+  "openclaw-basic-memory": {
     enabled: true
   }
 }
 ```
 
-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
 {
-  "basic-memory": {
+  "openclaw-basic-memory": {
     enabled: true,
     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 +163,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 +176,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 +295,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 +450,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
@@ -499,7 +507,7 @@ bun run test:int      # Real BM MCP integration tests
 
 ## Publish to npm
 
-This package is published as `@openclaw/basic-memory`.
+This package is published as `@basicmemory/openclaw-basic-memory`.
 
 ```bash
 # 1) Verify release readiness (types + tests + npm pack dry run)
@@ -531,9 +539,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 +570,29 @@ openclaw-basic-memory/
     └── recall.ts         # Auto-recall (active tasks + recent activity)
 ```
 
+## Telemetry
+
+Basic Memory collects anonymous, minimal usage events to understand how the CLI-to-cloud conversion funnel performs. This helps us prioritize features and improve the product.
+
+**What we collect:**
+- Cloud promo impressions (when the promo banner is shown)
+- Cloud login attempts and outcomes
+- Promo opt-out events
+
+**What we do NOT collect:**
+- No file contents, note titles, or knowledge base data
+- No personally identifiable information (PII)
+- No IP address tracking or fingerprinting
+- No per-command or per-tool-call tracking
+
+Events are sent to our [Umami Cloud](https://umami.is) instance, an open-source, privacy-focused analytics platform. Events are fire-and-forget on a background thread — analytics never blocks or slows the CLI.
+
+**Opt out** by setting the environment variable:
+
+```bash
+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/dashboard/index.html

@@ -0,0 +1,182 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Memory Dashboard</title>
+<style>
+* { margin: 0; padding: 0; box-sizing: border-box; }
+body { background: #0a0a0a; color: #e0e0e0; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; }
+code, .mono { font-family: 'SF Mono', 'Fira Code', 'Consolas', monospace; }
+
+/* Stats Bar */
+.stats-bar {
+  display: flex; gap: 24px; padding: 16px 24px;
+  background: #111; border-bottom: 1px solid #222;
+}
+.stat { text-align: center; }
+.stat-value { font-size: 28px; font-weight: 700; }
+.stat-label { font-size: 12px; color: #888; text-transform: uppercase; letter-spacing: 0.5px; }
+.stat-active .stat-value { color: #3b82f6; }
+.stat-done .stat-value { color: #22c55e; }
+.stat-explore .stat-value { color: #a855f7; }
+.stat-total .stat-value { color: #e0e0e0; }
+
+/* Layout */
+.main { display: flex; height: calc(100vh - 70px); }
+.kanban-area { flex: 1; overflow-x: auto; padding: 16px; }
+.sidebar { width: 320px; border-left: 1px solid #222; padding: 16px; overflow-y: auto; flex-shrink: 0; }
+
+/* Kanban */
+.kanban { display: flex; gap: 12px; height: 100%; }
+.column { flex: 1; min-width: 220px; background: #111; border-radius: 8px; display: flex; flex-direction: column; }
+.column-header { padding: 12px; font-weight: 600; font-size: 13px; text-transform: uppercase; letter-spacing: 0.5px; border-bottom: 2px solid; }
+.col-active .column-header { border-color: #3b82f6; color: #3b82f6; }
+.col-blocked .column-header { border-color: #ef4444; color: #ef4444; }
+.col-done .column-header { border-color: #22c55e; color: #22c55e; }
+.col-abandoned .column-header { border-color: #6b7280; color: #6b7280; }
+.column-body { padding: 8px; overflow-y: auto; flex: 1; }
+
+/* Cards */
+.card {
+  background: #1a1a1a; border: 1px solid #333; border-radius: 6px;
+  padding: 10px; margin-bottom: 8px; cursor: pointer; transition: border-color 0.15s;
+}
+.card:hover { border-color: #555; }
+.card-title { font-size: 13px; font-weight: 600; margin-bottom: 6px; word-break: break-word; }
+.card-meta { font-size: 11px; color: #888; font-family: 'SF Mono', monospace; }
+.card-meta span { margin-right: 10px; }
+.card-detail { display: none; margin-top: 8px; font-size: 12px; color: #aaa; border-top: 1px solid #333; padding-top: 8px; }
+.card.expanded .card-detail { display: block; }
+
+/* Sidebar */
+.sidebar h2 { font-size: 14px; text-transform: uppercase; letter-spacing: 0.5px; color: #888; margin-bottom: 12px; }
+.activity-item {
+  padding: 8px 0; border-bottom: 1px solid #1a1a1a; font-size: 13px;
+}
+.activity-title { font-weight: 500; }
+.activity-time { font-size: 11px; color: #666; font-family: 'SF Mono', monospace; }
+
+/* Refresh indicator */
+.refresh { position: fixed; top: 8px; right: 8px; font-size: 11px; color: #444; }
+
+@media (max-width: 900px) {
+  .main { flex-direction: column; }
+  .sidebar { width: 100%; border-left: none; border-top: 1px solid #222; max-height: 300px; }
+  .kanban { flex-wrap: wrap; }
+  .column { min-width: 180px; }
+}
+</style>
+</head>
+<body>
+
+<div class="stats-bar" id="stats-bar">
+  <div class="stat stat-total"><div class="stat-value" id="stat-total">-</div><div class="stat-label">Total Notes</div></div>
+  <div class="stat stat-active"><div class="stat-value" id="stat-active">-</div><div class="stat-label">Active Tasks</div></div>
+  <div class="stat stat-done"><div class="stat-value" id="stat-done">-</div><div class="stat-label">Completed</div></div>
+  <div class="stat stat-explore"><div class="stat-value" id="stat-explore">-</div><div class="stat-label">Explorations</div></div>
+</div>
+
+<div class="main">
+  <div class="kanban-area">
+    <div class="kanban">
+      <div class="column col-active"><div class="column-header">Active <span class="col-count"></span></div><div class="column-body" id="col-active"></div></div>
+      <div class="column col-blocked"><div class="column-header">Blocked <span class="col-count"></span></div><div class="column-body" id="col-blocked"></div></div>
+      <div class="column col-done"><div class="column-header">Done <span class="col-count"></span></div><div class="column-body" id="col-done"></div></div>
+      <div class="column col-abandoned"><div class="column-header">Abandoned <span class="col-count"></span></div><div class="column-body" id="col-abandoned"></div></div>
+    </div>
+  </div>
+  <div class="sidebar">
+    <h2>Activity Feed</h2>
+    <div id="activity-feed"></div>
+  </div>
+</div>
+
+<div class="refresh" id="refresh">⏳</div>
+
+<script>
+const API = '';
+
+function makeCard(task) {
+  const fm = task.frontmatter || {};
+  const status = (fm.status || 'active').toLowerCase();
+  const step = fm.current_step || '?';
+  const total = fm.total_steps || '?';
+  const assigned = fm.assigned_to || '';
+  const div = document.createElement('div');
+  div.className = 'card';
+  div.innerHTML = `
+    <div class="card-title">${esc(task.title)}</div>
+    <div class="card-meta">
+      ${assigned ? `<span>👤 ${esc(assigned)}</span>` : ''}
+      <span>📊 ${esc(String(step))}/${esc(String(total))}</span>
+    </div>
+    <div class="card-detail mono">${esc(task.content || '').slice(0, 300)}</div>
+  `;
+  div.onclick = () => div.classList.toggle('expanded');
+  return { el: div, status };
+}
+
+function esc(s) { const d = document.createElement('div'); d.textContent = s; return d.innerHTML; }
+
+async function fetchJson(url) {
+  try { const r = await fetch(url); return r.ok ? r.json() : null; } catch { return null; }
+}
+
+async function refresh() {
+  document.getElementById('refresh').textContent = '🔄';
+
+  const [tasks, activity, stats] = await Promise.all([
+    fetchJson(`${API}/api/tasks`),
+    fetchJson(`${API}/api/activity`),
+    fetchJson(`${API}/api/stats`),
+  ]);
+
+  // Stats
+  if (stats) {
+    document.getElementById('stat-total').textContent = stats.totalNotes;
+    document.getElementById('stat-active').textContent = stats.activeTasks;
+    document.getElementById('stat-done').textContent = stats.completedTasks;
+    document.getElementById('stat-explore').textContent = stats.explorations;
+  }
+
+  // Kanban
+  const cols = { active: [], blocked: [], done: [], abandoned: [] };
+  if (tasks) {
+    for (const t of tasks) {
+      const { el, status } = makeCard(t);
+      const bucket = cols[status] ? status : 'active';
+      cols[bucket].push(el);
+    }
+  }
+  for (const [key, items] of Object.entries(cols)) {
+    const container = document.getElementById(`col-${key}`);
+    container.innerHTML = '';
+    for (const el of items) container.appendChild(el);
+    container.parentElement.querySelector('.col-count').textContent = `(${items.length})`;
+  }
+
+  // Activity
+  const feed = document.getElementById('activity-feed');
+  feed.innerHTML = '';
+  if (activity?.length) {
+    for (const a of activity.slice(0, 30)) {
+      const div = document.createElement('div');
+      div.className = 'activity-item';
+      const time = a.created_at ? new Date(a.created_at).toLocaleTimeString() : '';
+      div.innerHTML = `<div class="activity-title">${esc(a.title)}</div><div class="activity-time">${time}</div>`;
+      feed.appendChild(div);
+    }
+  } else {
+    feed.innerHTML = '<div style="color:#555">No recent activity</div>';
+  }
+
+  document.getElementById('refresh').textContent = '✓';
+  setTimeout(() => { document.getElementById('refresh').textContent = ''; }, 2000);
+}
+
+refresh();
+setInterval(refresh, 30000);
+</script>
+</body>
+</html>

package/dashboard/server.ts

@@ -0,0 +1,146 @@
+import { readFileSync } from "node:fs"
+import {
+  createServer,
+  type IncomingMessage,
+  type Server,
+  type ServerResponse,
+} from "node:http"
+import { join } from "node:path"
+import type { BmClient, SearchResult } from "../bm-client.ts"
+
+export interface DashboardServerOptions {
+  port: number
+  client: BmClient
+}
+
+export function createDashboardServer(options: DashboardServerOptions): Server {
+  const { client, port } = options
+
+  const indexHtml = readFileSync(
+    join(import.meta.dirname ?? __dirname, "index.html"),
+    "utf-8",
+  )
+
+  const server = createServer(
+    async (req: IncomingMessage, res: ServerResponse) => {
+      const url = new URL(req.url ?? "/", `http://localhost:${port}`)
+      const path = url.pathname
+
+      try {
+        if (path === "/" && req.method === "GET") {
+          res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" })
+          res.end(indexHtml)
+          return
+        }
+
+        if (path === "/api/tasks" && req.method === "GET") {
+          const results = await client.search("type:Task", 50, undefined, {
+            filters: { type: "Task" },
+          })
+          const tasks = await enrichWithFrontmatter(client, results)
+          json(res, tasks)
+          return
+        }
+
+        if (path === "/api/activity" && req.method === "GET") {
+          const results = await client.recentActivity("24h")
+          json(res, results)
+          return
+        }
+
+        if (path === "/api/explorations" && req.method === "GET") {
+          const results = await client.search(
+            "type:Exploration",
+            50,
+            undefined,
+            {
+              filters: { type: "Exploration" },
+            },
+          )
+          json(res, results)
+          return
+        }
+
+        if (path === "/api/notes/daily" && req.method === "GET") {
+          const today = new Date().toISOString().split("T")[0]
+          const results = await client.search(today, 5)
+          const daily = results.filter((r) => r.title.includes(today))
+          json(res, daily)
+          return
+        }
+
+        if (path === "/api/stats" && req.method === "GET") {
+          const [allNotes, tasks, explorations] = await Promise.all([
+            client.recentActivity("720h").catch(() => []),
+            client
+              .search("type:Task", 100, undefined, {
+                filters: { type: "Task" },
+              })
+              .catch(() => []),
+            client
+              .search("type:Exploration", 100, undefined, {
+                filters: { type: "Exploration" },
+              })
+              .catch(() => []),
+          ])
+
+          const tasksWithFm = await enrichWithFrontmatter(client, tasks)
+          const active = tasksWithFm.filter(
+            (t) => t.frontmatter?.status === "active",
+          ).length
+          const completed = tasksWithFm.filter(
+            (t) =>
+              t.frontmatter?.status === "done" ||
+              t.frontmatter?.status === "completed",
+          ).length
+
+          json(res, {
+            totalNotes: allNotes.length,
+            activeTasks: active,
+            completedTasks: completed,
+            explorations: explorations.length,
+          })
+          return
+        }
+
+        res.writeHead(404, { "Content-Type": "application/json" })
+        res.end(JSON.stringify({ error: "not found" }))
+      } catch (err: unknown) {
+        const message = err instanceof Error ? err.message : String(err)
+        res.writeHead(500, { "Content-Type": "application/json" })
+        res.end(JSON.stringify({ error: message }))
+      }
+    },
+  )
+
+  return server
+}
+
+function json(res: ServerResponse, data: unknown): void {
+  res.writeHead(200, {
+    "Content-Type": "application/json",
+    "Access-Control-Allow-Origin": "*",
+  })
+  res.end(JSON.stringify(data))
+}
+
+async function enrichWithFrontmatter(
+  client: BmClient,
+  results: SearchResult[],
+): Promise<
+  Array<SearchResult & { frontmatter?: Record<string, unknown> | null }>
+> {
+  const enriched = await Promise.all(
+    results.map(async (r) => {
+      try {
+        const note = await client.readNote(r.permalink, {
+          includeFrontmatter: true,
+        })
+        return { ...r, frontmatter: note.frontmatter ?? null }
+      } catch {
+        return { ...r, frontmatter: null }
+      }
+    }),
+  )
+  return enriched
+}

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"
@@ -30,7 +37,7 @@ import { registerSearchTool } from "./tools/search-notes.ts"
 import { registerWriteTool } from "./tools/write-note.ts"
 
 export default {
-  id: "basic-memory",
+  id: "openclaw-basic-memory",
   name: "Basic Memory",
   description:
     "Local-first knowledge graph for OpenClaw — persistent memory with graph search and composited memory_search",
@@ -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,8 +89,10 @@ export default {
     registerCli(api, client, cfg)
 
     // --- Service lifecycle ---
+    let dashboardServer: Server | undefined
+
     api.registerService({
-      id: "basic-memory",
+      id: "openclaw-basic-memory",
       start: async (ctx: { config?: unknown; workspaceDir?: string }) => {
         log.info("starting...")
 
@@ -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

@@ -1,5 +1,5 @@
 {
-  "id": "basic-memory",
+  "id": "openclaw-basic-memory",
   "kind": "memory",
   "skills": [
     "skills/memory-tasks",
@@ -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.1",
+  "version": "0.1.0-alpha.10",
   "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",
@@ -29,6 +34,8 @@
     "tools/write-note.ts",
     "types/openclaw.d.ts",
     "schema/task-schema.ts",
+    "dashboard/server.ts",
+    "dashboard/index.html",
     "skills/",
     "scripts/setup-bm.sh",
     "openclaw.plugin.json",

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 ────────────────────────────────────────────────────────