@basicmemory/openclaw-basic-memory 0.1.0-alpha.12 → 0.1.0-alpha.13

package/README.md

@@ -1,131 +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
 
-# Restart the gateway
-openclaw gateway restart
-```
+**Prerequisite:** [uv](https://docs.astral.sh/uv/) (Python package manager) — used to install the Basic Memory CLI.
 
-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:
-
-```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`
+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.
 
-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": {
@@ -134,459 +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...
+| 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 |
 
-## 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:
+## How it works
 
-- 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
----
+### Memory search
 
-## Context
-Rolling JWT middleware to all API routes. Staging verification is in progress.
+When your agent calls `memory_search`, three sources are queried in parallel:
 
-## Plan
-- [x] Implement middleware
-- [x] Add refresh-token validation
-- [ ] Roll out to staging
-- [ ] Verify logs and error rates
-```
+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
 
-To mark complete, update:
+Results come back in clear sections so the agent knows where each piece of context came from.
 
-```yaml
-status: done
-```
+### Auto-recall
 
-Done tasks are filtered out of the `Active Tasks` section in composited `memory_search`.
+On each session start, the plugin loads active tasks and recently modified notes, giving the agent immediate awareness of ongoing work without being asked.
 
-### 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
+### Auto-capture
 
-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.
+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.
 
-### 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)
+### Persistent connection
 
-## Agent Tools
+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.
 
-All content tools accept an optional `project` parameter to operate on a different project than the default (cross-project operations).
+## Agent tools
 
-### `list_workspaces`
-List all workspaces (personal and organization) accessible to this user.
-```
-list_workspaces()
-```
+All tools accept an optional `project` parameter for cross-project operations.
 
-### `list_memory_projects`
-List all projects, optionally filtered by workspace.
-```
-list_memory_projects()
-list_memory_projects(workspace="my-org")
-```
+| 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 |
 
-### `search_notes`
-Search the knowledge graph.
-```
-search_notes(query="API design", limit=5)
-search_notes(query="API design", project="other-project")  # cross-project
-```
-
-### `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
-```
-
-### `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
-```
-
-### `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",
-)
-```
-
-### `delete_note`
-Delete a note.
-```
-delete_note(identifier="notes/old-draft")
-delete_note(identifier="notes/old-draft", project="archive")  # cross-project
-```
-
-### `move_note`
-Move a note to a different folder.
-```
-move_note(identifier="notes/my-note", newFolder="archive")
-```
-
-### `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
-```
-
-### `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
-```
-
-### `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
-
-### 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 |
-
-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
-```
+| `/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 |
 
-## 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
+## Bundled skills
 
-### `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.
+Six skills ship with the plugin — no installation needed:
 
-### `edit_note` says `edit-note` is required
-Your installed `basic-memory` version is missing native `tool edit-note`.
-Upgrade `basic-memory` and rerun.
+- **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
 
-### Jiti cache issues
-```bash
-rm -rf /tmp/jiti/ "$TMPDIR/jiti/"
-openclaw gateway stop && openclaw gateway start
-```
+### Updating skills
 
-### 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
-
-This repo includes real end-to-end integration tests for `BmClient` in:
-
-- `integration/bm-client.integration.test.ts`
-
-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:
-
-```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 itself does not collect any telemetry. However, the **Basic Memory CLI** (`bm`) that the plugin spawns may send anonymous usage analytics. See the [Basic Memory documentation](https://github.com/basicmachines-co/basic-memory) for details.
-
-To opt out of Basic Memory CLI telemetry:
-
-```bash
-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

@@ -659,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)

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,5 +1,5 @@
 import { execSync } from "node:child_process"
-import type { Server } from "node:http"
+
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
 import { BmClient } from "./bm-client.ts"
 import { registerCli } from "./commands/cli.ts"
@@ -10,7 +10,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"
@@ -83,8 +83,6 @@ 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 }) => {
@@ -147,30 +145,10 @@ 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}`,
-            )
-          })
-        }
-
         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.12",
+  "version": "0.1.0-alpha.13",
   "type": "module",
   "description": "Basic Memory plugin for OpenClaw — local-first knowledge graph for agent memory",
   "license": "MIT",
@@ -33,8 +33,6 @@
     "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/dashboard/index.html

@@ -1,182 +0,0 @@
-<!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

@@ -1,146 +0,0 @@
-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
-}