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

package/README.md

@@ -1,134 +1,66 @@
 # openclaw-basic-memory
 
-Local-first knowledge graph plugin for OpenClaw — persistent memory with graph search and composited memory search. Everything works locally with no cloud account required.
+Give your OpenClaw agent persistent, searchable memory — in plain text files you can read and edit.
 
-## What this plugin does
+## What is Basic Memory?
 
-The `openclaw-basic-memory` plugin integrates [Basic Memory](https://github.com/basicmachines-co/basic-memory) with OpenClaw to provide:
+[Basic Memory](https://basicmemory.com) stores AI knowledge in local Markdown files and indexes them into a semantic knowledge graph. Your agent writes notes. You can open them in any editor, read them, change them, and the changes sync back automatically. No black box. No proprietary format. Just files.
 
-- **Composited `memory_search`** — queries MEMORY.md, the BM knowledge graph, and active tasks in parallel
-- **Persistent MCP stdio session** — keeps a single `bm mcp --transport stdio --project <name>` process alive
-- **Auto-recall** — injects active tasks and recent activity as context at session start
-- **Auto-capture** — records agent conversations as structured daily notes
-- **Graph tools** — search, read, write, edit, delete, move, and navigate notes via `memory://` URLs
-- **Skill workflows** — `/tasks`, `/reflect`, `/defrag`, `/schema` slash commands for guided memory management
+It does three things that work together:
 
-All data stays on your machine as markdown files indexed locally with SQLite. Cloud sync is available but entirely optional — see [BASIC_MEMORY.md](./BASIC_MEMORY.md) for cloud setup.
+- **Stores knowledge in plain Markdown** — everything lives in plain text files on your computer, not locked inside a database you can't read
+- **Creates connections automatically** — notes link to each other through a searchable, traversable knowledge graph
+- **Searches by meaning, not just keywords** — vector search finds relevant context even when the exact words don't match
+- **Keeps notes consistent** — dynamic schemas and validation ensure your knowledge base stays structured and useful as it grows
+- **Enables two-way collaboration** — both you and the AI read and write the same files
 
-For a practical runbook, see [Memory + Task Flow](./MEMORY_TASK_FLOW.md).
+Over time, your agent builds a knowledge base that grows with you. Context that survives across sessions. Memory that belongs to you.
 
-## Requirements
+Learn more: [basicmemory.com](https://basicmemory.com) · [GitHub](https://github.com/basicmachines-co/basic-memory) · [Docs](https://docs.basicmemory.com)
 
-1. **[uv](https://docs.astral.sh/uv/)** — Python package manager used to install Basic Memory CLI
-   ```bash
-   # macOS
-   brew install uv
+## What this plugin does
 
-   # macOS / Linux
-   curl -LsSf https://astral.sh/uv/install.sh | sh
-   ```
+This plugin connects Basic Memory to OpenClaw so your agent can:
 
-2. **[OpenClaw](https://docs.openclaw.ai)** with plugin support
+- **Remember across sessions** — search and recall past conversations, decisions, and context
+- **Track work in progress** — structured tasks that survive context compaction
+- **Build knowledge over time** — notes, observations, and relations that grow into a connected graph
+- **Search intelligently** — composited search across working memory, the knowledge graph, and active tasks in parallel
 
-## Installation
+All data stays on your machine as Markdown files indexed locally with SQLite. Cloud sync is available but entirely optional.
 
-```bash
-# Install the plugin (automatically installs the bm CLI via uv)
-openclaw plugins install @basicmemory/openclaw-basic-memory
+## Install
 
-# Enable and assign to the memory slot
-openclaw plugins enable openclaw-basic-memory --slot memory
+**Prerequisite:** [uv](https://docs.astral.sh/uv/) (Python package manager) — used to install the Basic Memory CLI.
 
-# Restart the gateway
-openclaw gateway restart
-```
-
-Verify:
 ```bash
-openclaw plugins list
-openclaw plugins info openclaw-basic-memory
-```
+# macOS
+brew install uv
 
-If `uv` is not installed, the `bm` CLI setup is skipped gracefully during install. Install `uv` first, then re-run the postinstall script:
-
-```bash
-bash ~/.openclaw/extensions/openclaw-basic-memory/scripts/setup-bm.sh
+# macOS / Linux
+curl -LsSf https://astral.sh/uv/install.sh | 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:
+Then install the plugin:
 
 ```bash
-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 openclaw-basic-memory --slot memory
+openclaw plugins install @basicmemory/openclaw-basic-memory
 openclaw gateway restart
 ```
 
-Or load directly from a path in your OpenClaw config:
+That's it. The plugin auto-installs the `bm` CLI on first startup if it's not already on your PATH. See [SECURITY.md](./SECURITY.md) for details on how this works.
 
-```json5
-{
-  plugins: {
-    load: {
-      paths: ["~/dev/openclaw-basic-memory"]
-    },
-    entries: {
-      "openclaw-basic-memory": {
-        enabled: true
-      }
-    },
-    slots: {
-      memory: "openclaw-basic-memory"
-    }
-  }
-}
-```
-
-### Bundled Skills
-
-This plugin ships with six skills that are automatically available when the plugin is enabled — no manual installation needed:
-
-- **`memory-tasks`** — structured task tracking that survives context compaction
-- **`memory-reflect`** — periodic consolidation of recent notes into durable memory
-- **`memory-defrag`** — periodic cleanup/reorganization of memory files
-- **`memory-schema`** — schema lifecycle management (infer, create, validate, diff, evolve)
-- **`memory-metadata-search`** — structured metadata search by custom frontmatter fields (status, priority, etc.)
-- **`memory-notes`** — guidance for writing well-structured notes with observations and relations
-
-Skills are loaded from the plugin's `skills/` directory. See the upstream source at [`basic-memory-skills`](https://github.com/basicmachines-co/basic-memory-skills).
-
-#### Updating or adding skills with `npx skills`
-
-You can update bundled skills or install new ones as they become available using the [Skills CLI](https://github.com/vercel-labs/skills):
+Verify:
 
 ```bash
-# Update all basic-memory skills to latest
-npx skills add basicmachines-co/basic-memory-skills --agent openclaw
-
-# Install a specific skill
-npx skills add basicmachines-co/basic-memory-skills --name memory-tasks --agent openclaw
+openclaw plugins list
+openclaw plugins info openclaw-basic-memory
 ```
 
-This installs to the same `skills/` directory the plugin reads from, so updated skills take effect on the next session.
-
 ## Configuration
 
-### Minimal (zero-config)
+### Zero-config (recommended)
+
 ```json5
 {
   "openclaw-basic-memory": {
@@ -137,476 +69,180 @@ 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 root, sets it as the default BM project, and captures conversations.
+This uses sensible defaults: auto-generated project name, maps to your workspace root, captures conversations, and recalls active tasks on session start.
+
+### Full options
 
-### Full configuration
 ```json5
 {
   "openclaw-basic-memory": {
     enabled: true,
     config: {
-      project: "my-agent",                          // BM project name (default: "openclaw-{hostname}")
-      bmPath: "bm",                                 // Path to BM CLI binary
-      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
-      captureMinChars: 10,                           // Min chars to trigger auto-capture
-      autoRecall: true,                              // Inject active tasks + recent activity at session start
-      recallPrompt: "Check for active tasks and recent activity. Summarize anything relevant to the current session.",
-      debug: false,                                  // Verbose logging
+      project: "my-agent",        // BM project name (default: "openclaw-{hostname}")
+      projectPath: ".",            // Project directory (default: workspace root)
+      memoryDir: "memory/",        // Where task notes live
+      memoryFile: "MEMORY.md",     // Working memory file
+      autoCapture: true,           // Record conversations as daily notes
+      autoRecall: true,            // Inject active tasks + recent activity at session start
+      debug: false                 // Verbose logging
     }
   }
 }
 ```
 
-### Configuration Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `project` | string | `"openclaw-{hostname}"` | Basic Memory project name |
-| `bmPath` | string | `"bm"` | Path to Basic Memory CLI binary |
-| `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 |
-| `captureMinChars` | number | `10` | Minimum character threshold for auto-capture (both messages must be shorter to skip) |
-| `autoRecall` | boolean | `true` | Inject active tasks and recent activity as context at session start |
-| `recallPrompt` | string | *(see above)* | Instruction appended to recalled context — customize to change what the agent focuses on |
-| `debug` | boolean | `false` | Enable verbose debug logs |
-
-Snake_case aliases (`memory_dir`, `memory_file`, `auto_recall`, `recall_prompt`, `capture_min_chars`) are also supported.
-
-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, and sets it as the default Basic Memory project.
-
-## How It Works
-
-### MCP Session Lifecycle
-On startup, the plugin starts one persistent MCP stdio session:
-1. Spawns `bm mcp --transport stdio --project <name>`
-2. Verifies required MCP tool capabilities at connect time
-3. Uses bounded reconnect attempts (`500ms`, `1000ms`, `2000ms`) when the session drops
-
-Basic Memory MCP lifecycle handles sync and watch behavior for the project.
-
-### Composited `memory_search`
-When the agent calls `memory_search`, three sources are queried in parallel:
-
-1. **MEMORY.md** — grep/text search with ±1 line context
-2. **BM Knowledge Graph** — hybrid FTS + vector search (top 5 results with scores)
-3. **Active Tasks** — scans `memory/tasks/` for non-done tasks
-
-Results are formatted into clear sections:
-```
-## MEMORY.md
-- matching lines with context...
-
-## Knowledge Graph (memory/)
-- note-title (0.85)
-  > preview of content...
-
-## Active Tasks
-- **Task Name** (status: active, step: 3)
-  context snippet...
-```
-
-### Memory + Task Management Flow
-
-This plugin works best if you treat memory as three lanes:
-
-1. **Working memory (`MEMORY.md`)** — short-horizon context and current focus.
-2. **Knowledge graph (`memory/**/*.md`)** — long-term notes indexed by Basic Memory.
-3. **Task notes (`memory/tasks/*.md`)** — active execution state for in-flight work.
-
-> **Note:** OpenClaw's default convention treats `MEMORY.md` as [long-term curated memory](https://docs.openclaw.ai/concepts/memory). This plugin flips that role — the BM knowledge graph handles durable storage, so `MEMORY.md` serves as short-horizon working memory. See [MEMORY_TASK_FLOW.md](./MEMORY_TASK_FLOW.md) for details.
-
-Typical loop:
-
-1. Capture or update notes/tasks with `write_note` / `edit_note`.
-2. The persistent BM MCP process syncs markdown updates into the BM project index.
-3. `memory_search` queries:
-   - `MEMORY.md` text snippets
-   - BM search results (semantic + FTS)
-   - active tasks
-4. Drill into one result with `memory_get` or `read_note`.
-5. Advance tasks by updating `current_step`, checkboxes, and context.
-6. Complete tasks by setting `status: done` (done tasks are excluded from active task results).
-
-```mermaid
-flowchart LR
-    A["Write/Update notes"] --> B["BM MCP indexes changes"]
-    B --> C["memory_search(query)"]
-    C --> D["MEMORY.md"]
-    C --> E["Knowledge Graph"]
-    C --> F["Active Tasks"]
-    D --> G["Composited result"]
-    E --> G
-    F --> G
-    G --> H["memory_get / read_note"]
-    H --> A
-```
-
-### Task Note Shape (Recommended)
-
-`memory_search` task extraction is strongest when task notes include:
-
-- file location: `memory/tasks/*.md`
-- frontmatter fields: `status:` and `current_step:`
-- a `## Context` section for preview snippets
-
-Example:
-
-```markdown
----
-title: auth-middleware-rollout
-type: Task
-status: active
-current_step: 2
----
-
-## Context
-Rolling JWT middleware to all API routes. Staging verification is in progress.
-
-## Plan
-- [x] Implement middleware
-- [x] Add refresh-token validation
-- [ ] Roll out to staging
-- [ ] Verify logs and error rates
-```
-
-To mark complete, update:
-
-```yaml
-status: done
-```
-
-Done tasks are filtered out of the `Active Tasks` section in composited `memory_search`.
-
-### Auto-Recall
-On each `agent_start` event (when `autoRecall: true`), the plugin:
-1. Queries the knowledge graph for active tasks (`type: Task`, `status: active`, up to 5)
-2. Fetches notes modified in the last 24 hours
-3. Formats both into structured context and returns it to the agent
-
-This gives the agent immediate awareness of ongoing work and recent changes without the user needing to ask. The `recallPrompt` config field controls the instruction appended to the context — customize it to steer what the agent prioritizes.
+| Option | Default | Description |
+|--------|---------|-------------|
+| `project` | `"openclaw-{hostname}"` | Basic Memory project name |
+| `bmPath` | `"bm"` | Path to BM CLI binary |
+| `projectPath` | `"."` | Project data directory |
+| `memoryDir` | `"memory/"` | Relative path for task scanning |
+| `memoryFile` | `"MEMORY.md"` | Working memory file for text search |
+| `autoCapture` | `true` | Auto-index agent conversations |
+| `captureMinChars` | `10` | Min chars to trigger capture |
+| `autoRecall` | `true` | Inject context at session start |
+| `recallPrompt` | *(default)* | Instruction appended to recalled context |
+| `debug` | `false` | Verbose logs |
 
-### Auto-Capture
-After each agent turn (when `autoCapture: true`), the plugin:
-1. Extracts the last user + assistant messages
-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)
+## How it works
 
-## Agent Tools
+### Memory search
 
-All content tools accept an optional `project` parameter to operate on a different project than the default (cross-project operations).
+When your agent calls `memory_search`, three sources are queried in parallel:
 
-### `list_workspaces`
-List all workspaces (personal and organization) accessible to this user.
-```
-list_workspaces()
-```
+1. **MEMORY.md** — text search with surrounding context
+2. **Knowledge Graph** — hybrid full-text + vector search across all indexed notes
+3. **Active Tasks** — scans `memory/tasks/` for in-progress work
 
-### `list_memory_projects`
-List all projects, optionally filtered by workspace.
-```
-list_memory_projects()
-list_memory_projects(workspace="my-org")
-```
+Results come back in clear sections so the agent knows where each piece of context came from.
 
-### `search_notes`
-Search the knowledge graph.
-```
-search_notes(query="API design", limit=5)
-search_notes(query="API design", project="other-project")  # cross-project
-```
+### Auto-recall
 
-### `read_note`
-Read a note by title, permalink, or `memory://` URL.
-```
-read_note(identifier="memory://projects/api-redesign")
-read_note(identifier="memory://projects/api-redesign", include_frontmatter=true)  # raw markdown + YAML
-read_note(identifier="notes/readme", project="docs")  # cross-project
-```
+On each session start, the plugin loads active tasks and recently modified notes, giving the agent immediate awareness of ongoing work without being asked.
 
-### `write_note`
-Create a new note.
-```
-write_note(title="Auth Strategy", content="## Overview\n...", folder="decisions")
-write_note(title="Shared Note", content="...", folder="shared", project="team")  # cross-project
-```
+### Auto-capture
 
-### `edit_note`
-Edit an existing note (`append`, `prepend`, `find_replace`, `replace_section`).
-```
-edit_note(identifier="weekly-review", operation="append", content="\n## Update\nDone.")
-edit_note(
-  identifier="weekly-review",
-  operation="find_replace",
-  find_text="status: active",
-  content="status: done",
-  expected_replacements=1,
-)
-edit_note(
-  identifier="weekly-review",
-  operation="replace_section",
-  section="## This Week",
-  content="- Done\n- Next",
-)
-```
+After each conversation turn, the plugin records the exchange as a timestamped entry in a daily note. This builds a searchable history of everything your agent has discussed.
 
-### `delete_note`
-Delete a note.
-```
-delete_note(identifier="notes/old-draft")
-delete_note(identifier="notes/old-draft", project="archive")  # cross-project
-```
+### Persistent connection
 
-### `move_note`
-Move a note to a different folder.
-```
-move_note(identifier="notes/my-note", newFolder="archive")
-```
+The plugin keeps a long-lived Basic Memory process running over standard I/O. No cold starts per tool call. The connection auto-reconnects if it drops.
 
-### `build_context`
-Navigate the knowledge graph — get a note with its observations and relations.
-```
-build_context(url="memory://projects/api-redesign", depth=2)
-build_context(url="memory://decisions", depth=1, project="team")  # cross-project
-```
+## Agent tools
 
-### `schema_validate`
-Validate notes against their Picoschema definitions.
-```
-schema_validate(noteType="person")
-schema_validate(identifier="notes/john-doe")
-schema_validate(noteType="person", project="contacts")  # cross-project
-```
+All tools accept an optional `project` parameter for cross-project operations.
 
-### `schema_infer`
-Analyze existing notes and suggest a Picoschema definition.
-```
-schema_infer(noteType="meeting")
-schema_infer(noteType="person", threshold=0.5)
-```
-
-### `schema_diff`
-Detect drift between a schema definition and actual note usage.
-```
-schema_diff(noteType="person")
-```
-
-## Slash Commands
+| Tool | Description |
+|------|-------------|
+| `memory_search` | Composited search across all memory sources |
+| `memory_get` | Read a specific note by title or path |
+| `search_notes` | Search the knowledge graph directly |
+| `read_note` | Read a note by title, permalink, or `memory://` URL |
+| `write_note` | Create or update a note |
+| `edit_note` | Append, prepend, find/replace, or replace a section |
+| `delete_note` | Delete a note |
+| `move_note` | Move a note to a different folder |
+| `build_context` | Navigate the knowledge graph — follow relations and connections |
+| `list_memory_projects` | List accessible projects |
+| `list_workspaces` | List workspaces (personal and org) |
+| `schema_validate` | Validate notes against Picoschema definitions |
+| `schema_infer` | Analyze notes and suggest a schema |
+| `schema_diff` | Detect drift between schema and actual usage |
 
-### Memory
-- **`/remember <text>`** — Save a quick note to the knowledge graph
-- **`/recall <query>`** — Search the knowledge graph (top 5 results)
-
-### Skill workflows
-These inject step-by-step instructions from the bundled skill files. Each accepts optional arguments for context.
+## Slash commands
 
 | Command | Description |
 |---------|-------------|
-| `/tasks [args]` | Task management — create, track, resume structured tasks |
-| `/reflect [args]` | Memory reflection — consolidate recent activity into long-term memory |
-| `/defrag [args]` | Memory defrag — reorganize, split, prune memory files |
-| `/schema [args]` | Schema management — infer, create, validate, evolve Picoschema definitions |
+| `/remember <text>` | Save a quick note |
+| `/recall <query>` | Search the knowledge graph |
+| `/tasks [args]` | Create, track, resume structured tasks |
+| `/reflect [args]` | Consolidate recent notes into long-term memory |
+| `/defrag [args]` | Reorganize and clean up memory files |
+| `/schema [args]` | Manage Picoschema definitions |
 
-Examples:
-```
-/tasks create a task for the API migration
-/reflect
-/defrag clean up completed tasks older than 2 weeks
-/schema infer a schema for Meeting notes
-```
-
-## CLI Commands
+## CLI
 
 ```bash
 openclaw basic-memory search "auth patterns" --limit 5
 openclaw basic-memory read "projects/api-redesign"
-openclaw basic-memory read "projects/api-redesign" --raw
-openclaw basic-memory edit "projects/api-redesign" --operation append --content $'\n## Update\nDone.'
 openclaw basic-memory context "memory://projects/api-redesign" --depth 2
 openclaw basic-memory recent --timeframe 24h
 openclaw basic-memory status
 ```
 
-## Troubleshooting
-
-### `bm` command not found
-```bash
-which bm              # Check if installed
-bm --version          # Check version
-bm mcp --help         # Verify MCP server command exists
-```
-If `bm mcp` doesn't exist, update Basic Memory to a newer version.
-
-### `edit_note` says `edit-note` is required
-Your installed `basic-memory` version is missing native `tool edit-note`.
-Upgrade `basic-memory` and rerun.
-
-### Jiti cache issues
-```bash
-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
-3. Try `bm mcp --transport stdio --project <name>` and run `search_notes` through an MCP inspector/client
-4. Check project status: `bm project list`
-
-## Integration Tests
+## Bundled skills
 
-This repo includes real end-to-end integration tests for `BmClient` in:
+Six skills ship with the plugin — no installation needed:
 
-- `integration/bm-client.integration.test.ts`
+- **memory-tasks** — structured task tracking that survives context compaction
+- **memory-reflect** — periodic consolidation of recent notes into durable memory
+- **memory-defrag** — cleanup and reorganization of memory files
+- **memory-schema** — schema lifecycle (infer, create, validate, diff)
+- **memory-metadata-search** — query notes by frontmatter fields
+- **memory-notes** — guidance for writing well-structured notes
 
-These tests launch a real `bm mcp --transport stdio --project <name>` process,
-run write/read/edit/search/context/move/delete calls, and assert actual filesystem/index results.
-
-Run integration tests:
+### Updating skills
 
 ```bash
-bun run test:int
+npx skills add basicmachines-co/basic-memory-skills --agent openclaw
 ```
 
-By default this uses `./scripts/bm-local.sh`, which runs BM from a sibling
-`../basic-memory` checkout via `uv run --project ...` when present, and falls
-back to `bm` on `PATH` otherwise.
+## Task notes
 
-Optional overrides:
+The plugin works well with structured task notes in `memory/tasks/`:
 
-```bash
-# Use a non-default bm binary
-BM_BIN=/absolute/path/to/bm bun run test:int
-
-# Use a specific basic-memory source checkout
-BASIC_MEMORY_REPO=/absolute/path/to/basic-memory bun run test:int
-```
+```markdown
+---
+title: auth-middleware-rollout
+type: Task
+status: active
+current_step: 2
+---
 
-## Development
+## Context
+Rolling JWT middleware to all API routes.
 
-```bash
-bun run check-types   # Type checking
-bun run lint          # Linting
-bun test              # Run tests (156 tests)
-bun run test:int      # Real BM MCP integration tests
+## Plan
+- [x] Implement middleware
+- [x] Add refresh-token validation
+- [ ] Roll out to staging
+- [ ] Verify logs and error rates
 ```
 
-## Publish to npm
+Set `status: done` to mark complete. Done tasks are filtered out of active task results.
 
-This package is published as `@basicmemory/openclaw-basic-memory`.
+## Basic Memory Cloud
 
-```bash
-# 1) Verify release readiness (types + tests + npm pack dry run)
-just release-check
+Everything works locally. Cloud adds cross-device sync, team workspaces, and persistent memory for hosted agents.
 
-# 2) Inspect publish payload
-just release-pack
+- Same knowledge graph on laptop, desktop, and CI
+- Shared workspaces for teams
+- Durable memory for production agents
 
-# 3) Authenticate once (if needed)
-npm login
+Cloud extends local-first — still plain Markdown, still yours. [Start a free trial](https://basicmemory.com) and use code `BMCLAW` for 20% off for 3 months. See [BASIC_MEMORY.md](./BASIC_MEMORY.md) for setup.
 
-# 4) Publish current version from package.json
-just release-publish
-```
+## Troubleshooting
 
-For a full release (version bump + publish + push tag):
+**`bm` not found** — Install uv, then restart the gateway. Or install manually: `uv tool install basic-memory`
 
-```bash
-just release patch   # or: minor, major, 0.2.0, etc.
-```
+**Search returns nothing** — Check that Basic Memory connected (look for `connected to BM` in logs). Verify files exist in the project directory.
 
-### GitHub Actions CI/CD
+**Jiti cache issues** — `rm -rf /tmp/jiti/ "$TMPDIR/jiti/"` then restart the gateway.
 
-- CI workflow: `.github/workflows/ci.yml` runs on PRs and `main` pushes.
-- Release workflow: `.github/workflows/release.yml` runs manually (`workflow_dispatch`) and will:
-  1. run release checks
-  2. bump version and create a git tag
-  3. push commit + tag
-  4. publish to npm
-  5. create a GitHub release
+**Disable semantic search** — Set `BASIC_MEMORY_SEMANTIC_SEARCH_ENABLED=false` to fall back to full-text only.
 
-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.
+## More
 
-### Project Structure
-```
-openclaw-basic-memory/
-├── index.ts              # Plugin entry — manages MCP lifecycle, registers tools
-├── config.ts             # Configuration parsing
-├── bm-client.ts          # Persistent Basic Memory MCP stdio client
-├── tools/                       # Agent tools
-│   ├── search-notes.ts          # search_notes
-│   ├── read-note.ts             # read_note
-│   ├── write-note.ts            # write_note
-│   ├── edit-note.ts             # edit_note
-│   ├── delete-note.ts           # delete_note
-│   ├── move-note.ts             # move_note
-│   ├── build-context.ts         # build_context
-│   ├── list-memory-projects.ts  # list_memory_projects
-│   ├── list-workspaces.ts       # list_workspaces
-│   ├── schema-validate.ts       # schema_validate
-│   ├── schema-infer.ts          # schema_infer
-│   ├── schema-diff.ts           # schema_diff
-│   └── memory-provider.ts       # Composited memory_search + memory_get
-├── commands/
-│   ├── slash.ts          # /remember, /recall
-│   ├── skills.ts         # /tasks, /reflect, /defrag, /schema
-│   └── cli.ts            # openclaw basic-memory CLI
-└── hooks/
-    ├── capture.ts        # Auto-capture conversations
-    └── recall.ts         # Auto-recall (active tasks + recent activity)
-```
+- [Memory + Task Flow](./MEMORY_TASK_FLOW.md) — practical runbook
+- [Cloud Setup](./BASIC_MEMORY.md) — configure Basic Memory Cloud
+- [Security](./SECURITY.md) — how auto-installation and data handling work
+- [Development](./DEVELOPMENT.md) — contributing, tests, publishing
+- [Basic Memory docs](https://docs.basicmemory.com)
+- [Issues](https://github.com/basicmachines-co/openclaw-basic-memory/issues)
 
 ## 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
-```
+This plugin does not collect telemetry. The Basic Memory CLI may send anonymous usage analytics — see the [Basic Memory docs](https://github.com/basicmachines-co/basic-memory) for opt-out instructions.
 
 ## License
 
-MIT — see LICENSE file.
-
-## Links
-
-- [Basic Memory](https://github.com/basicmachines-co/basic-memory)
-- [Basic Memory Skills](https://github.com/basicmachines-co/basic-memory-skills)
-- [OpenClaw](https://docs.openclaw.ai)
-- [Issues](https://github.com/basicmachines-co/openclaw-basic-memory/issues)
+MIT

package/bm-client.ts

@@ -1,7 +1,6 @@
 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]
@@ -197,7 +196,7 @@ function isRecoverableConnectionError(err: unknown): boolean {
   )
 }
 
-function isNoteNotFoundError(err: unknown): boolean {
+function _isNoteNotFoundError(err: unknown): boolean {
   const msg = getErrorMessage(err).toLowerCase()
   return (
     msg.includes("entity not found") ||
@@ -450,7 +449,6 @@ 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) {
@@ -661,11 +659,12 @@ export class BmClient {
       identifier,
       operation,
       content,
-      find_text: options.find_text,
-      section: options.section,
-      expected_replacements: options.expected_replacements,
       output_format: "json",
     }
+    if (options.find_text) args.find_text = options.find_text
+    if (options.section) args.section = options.section
+    if (options.expected_replacements != null)
+      args.expected_replacements = options.expected_replacements
     if (project) args.project = project
 
     const payload = await this.callTool("edit_note", args)
@@ -831,10 +830,6 @@ export class BmClient {
     return payload as unknown as MetadataSearchResult
   }
 
-  private isNoteNotFoundError(err: unknown): boolean {
-    return isNoteNotFoundError(err)
-  }
-
   async indexConversation(
     userMessage: string,
     assistantResponse: string,
@@ -856,22 +851,33 @@ export class BmClient {
       "---",
     ].join("\n")
 
+    // Try append first — if it fails for ANY reason, fall through to create
     try {
       await this.editNote(title, "append", entry)
       log.debug(`appended conversation to: ${title}`)
+      return
     } catch (err) {
-      if (!this.isNoteNotFoundError(err)) {
-        log.error("conversation append failed", err)
-        return
-      }
+      log.debug(`append failed, will create: ${getErrorMessage(err)}`)
+    }
 
-      const content = [`# Conversations ${dateStr}`, "", entry].join("\n")
-      try {
-        await this.writeNote(title, content, "conversations")
-        log.debug(`created conversation note: ${title}`)
-      } catch (createErr) {
-        log.error("conversation index failed", createErr)
-      }
+    // Create the note with frontmatter and first entry
+    const content = [
+      "---",
+      `title: Conversations ${dateStr}`,
+      "type: Conversation",
+      `date: "${dateStr}"`,
+      "---",
+      "",
+      `# Conversations ${dateStr}`,
+      "",
+      entry,
+    ].join("\n")
+
+    try {
+      await this.writeNote(title, content, "conversations")
+      log.debug(`created conversation note: ${title}`)
+    } catch (err) {
+      log.error("conversation index failed", err)
     }
   }
 

package/config.ts

@@ -6,11 +6,6 @@ export type CloudConfig = {
   api_key: string
 }
 
-export type DashboardConfig = {
-  enabled: boolean
-  port: number
-}
-
 export type BasicMemoryConfig = {
   project: string
   bmPath: string
@@ -23,7 +18,6 @@ export type BasicMemoryConfig = {
   recallPrompt: string
   debug: boolean
   cloud?: CloudConfig
-  dashboard: DashboardConfig
 }
 
 const ALLOWED_KEYS = [
@@ -43,7 +37,6 @@ const ALLOWED_KEYS = [
   "recall_prompt",
   "debug",
   "cloud",
-  "dashboard",
 ]
 
 function assertAllowedKeys(
@@ -113,22 +106,6 @@ 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
@@ -167,7 +144,6 @@ 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,10 +1,6 @@
-import type { Server } from "node:http"
+import { execSync } from "node:child_process"
+
 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"
@@ -14,10 +10,11 @@ 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"
+import { CONVERSATION_SCHEMA_CONTENT } from "./schema/conversation-schema.ts"
 import { TASK_SCHEMA_CONTENT } from "./schema/task-schema.ts"
 import { registerContextTool } from "./tools/build-context.ts"
 import { registerDeleteTool } from "./tools/delete-note.ts"
@@ -53,8 +50,6 @@ 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) ---
@@ -89,13 +84,47 @@ 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 }) => {
         log.info("starting...")
 
+        // Auto-install bm CLI if not found
+        const bmBin = cfg.bmPath || "bm"
+        try {
+          execSync(`command -v ${bmBin}`, { stdio: "ignore" })
+        } catch {
+          log.info("bm CLI not found on PATH — attempting auto-install...")
+          try {
+            execSync("command -v uv", { stdio: "ignore" })
+            log.info(
+              "installing basic-memory via uv (this may take a minute)...",
+            )
+            const result = execSync(
+              'uv tool install "basic-memory @ git+https://github.com/basicmachines-co/basic-memory.git@main" --force',
+              { encoding: "utf-8", timeout: 120_000, stdio: "pipe" },
+            )
+            log.info(
+              `basic-memory installed: ${result.trim().split("\n").pop()}`,
+            )
+            // Verify it worked
+            try {
+              execSync(`command -v ${bmBin}`, { stdio: "ignore" })
+              log.info("bm CLI now available on PATH")
+            } catch {
+              log.error(
+                "bm installed but not found on PATH. You may need to add uv's bin directory to your PATH (typically ~/.local/bin).",
+              )
+            }
+          } catch (_uvErr) {
+            log.error(
+              "Cannot auto-install basic-memory: uv not found. " +
+                "Install uv first (brew install uv, or curl -LsSf https://astral.sh/uv/install.sh | sh), " +
+                "then restart the gateway.",
+            )
+          }
+        }
+
         const workspace = ctx.workspaceDir ?? process.cwd()
         const projectPath = resolveProjectPath(cfg.projectPath, workspace)
         cfg.projectPath = projectPath
@@ -104,46 +133,30 @@ export default {
         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 {
+        // Seed schemas if not already present
+        for (const [name, content] of [
+          ["Task", TASK_SCHEMA_CONTENT],
+          ["Conversation", CONVERSATION_SCHEMA_CONTENT],
+        ] as const) {
           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)
+            await client.readNote(`schema/${name}`)
+            log.debug(`${name} schema already exists, skipping seed`)
+          } catch {
+            try {
+              await client.writeNote(name, content, "schema")
+              log.debug(`seeded ${name} schema note`)
+            } catch (err) {
+              log.debug(`${name} schema seed failed (non-fatal)`, err)
+            }
           }
         }
 
         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

@@ -56,11 +56,6 @@
       "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": {
@@ -81,13 +76,6 @@
           "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,6 +1,6 @@
 {
   "name": "@basicmemory/openclaw-basic-memory",
-  "version": "0.1.0-alpha.9",
+  "version": "0.1.1",
   "type": "module",
   "description": "Basic Memory plugin for OpenClaw — local-first knowledge graph for agent memory",
   "license": "MIT",
@@ -9,7 +9,6 @@
     "url": "https://github.com/basicmachines-co/openclaw-basic-memory"
   },
   "files": [
-    "analytics.ts",
     "index.ts",
     "bm-client.ts",
     "config.ts",
@@ -34,6 +33,7 @@
     "tools/write-note.ts",
     "types/openclaw.d.ts",
     "schema/task-schema.ts",
+    "schema/conversation-schema.ts",
     "skills/",
     "scripts/setup-bm.sh",
     "openclaw.plugin.json",

package/schema/conversation-schema.ts

@@ -0,0 +1,33 @@
+/**
+ * Canonical Conversation 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 CONVERSATION_SCHEMA_CONTENT = `---
+title: Conversation
+type: schema
+entity: Conversation
+version: 1
+schema:
+  date: "string, ISO date YYYY-MM-DD"
+  session_id?: "string, unique session identifier"
+  channel?: "string, where the conversation happened (webchat, telegram, discord, etc)"
+  participants?: "array, who was in the conversation"
+  topic?: "string, brief description of main topic"
+  summary?: "string, one-paragraph summary of key points"
+  key_decisions?: "array, decisions made during conversation"
+  action_items?: "array, things to do as a result"
+settings:
+  validation: warn
+---
+
+# Conversation
+
+A record of a conversation session between the agent and user(s).
+
+## Observations
+- [convention] Conversation files live in memory/conversations/ with format conversations-YYYY-MM-DD.md
+- [convention] Messages are appended as the conversation progresses
+- [convention] Summary and key_decisions populated at session end or by memory-reflect
+- [convention] Skip routine greetings, heartbeat acks, and tool call details
+- [convention] Focus on decisions, actions taken, and key context needed for continuity
+`

package/analytics.ts

@@ -1,162 +0,0 @@
-/**
- * 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)
-  }
-}