@basicmemory/openclaw-basic-memory 0.1.0-alpha.8 → 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
-
-The `openclaw-basic-memory` plugin integrates [Basic Memory](https://github.com/basicmachines-co/basic-memory) with OpenClaw to provide:
+## What is Basic Memory?
 
-- **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
+[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.
 
-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.
+It does three things that work together:
 
-For a practical runbook, see [Memory + Task Flow](./MEMORY_TASK_FLOW.md).
+- **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
 
-## Requirements
+Over time, your agent builds a knowledge base that grows with you. Context that survives across sessions. Memory that belongs to you.
 
-1. **[uv](https://docs.astral.sh/uv/)** — Python package manager used to install Basic Memory CLI
-   ```bash
-   # macOS
-   brew install uv
+Learn more: [basicmemory.com](https://basicmemory.com) · [GitHub](https://github.com/basicmachines-co/basic-memory) · [Docs](https://docs.basicmemory.com)
 
-   # macOS / Linux
-   curl -LsSf https://astral.sh/uv/install.sh | sh
-   ```
+## What this plugin does
 
-2. **[OpenClaw](https://docs.openclaw.ai)** with plugin support
+This plugin connects Basic Memory to OpenClaw so your agent can:
 
-## Installation
+- **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
 
-```bash
-# Install the plugin (automatically installs the bm CLI via uv)
-openclaw plugins install @basicmemory/openclaw-basic-memory
+All data stays on your machine as Markdown files indexed locally with SQLite. Cloud sync is available but entirely optional.
 
-# Enable and assign to the memory slot
-openclaw plugins enable openclaw-basic-memory --slot 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
-```
-
-If `uv` is not installed, the `bm` CLI setup is skipped gracefully during install. Install `uv` first, then re-run the postinstall script:
+# macOS
+brew install uv
 
-```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,440 +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 `memory/` directory, 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: "~/.openclaw/workspace/memory/",   // Optional override; 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 | 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 |
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `project` | string | `"openclaw-{hostname}"` | Basic Memory project name |
-| `bmPath` | string | `"bm"` | Path to Basic Memory CLI binary |
-| `projectPath` | string | `"memory/"` | Directory for BM project data (resolved from workspace unless absolute) |
-| `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 |
+## How it works
 
-Snake_case aliases (`memory_dir`, `memory_file`, `auto_recall`, `recall_prompt`, `capture_min_chars`) are also supported.
+### Memory search
 
-Cloud sync is optional — see [BASIC_MEMORY.md](./BASIC_MEMORY.md) for cloud configuration.
+When your agent calls `memory_search`, three sources are queried in parallel:
 
-On startup, the plugin ensures the configured BM project exists at `projectPath` via MCP `create_memory_project` in idempotent mode.
+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
 
-## How It Works
+Results come back in clear sections so the agent knows where each piece of context came from.
 
-### 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
+### Auto-recall
 
-Basic Memory MCP lifecycle handles sync and watch behavior for the 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.
 
-### Composited `memory_search`
-When the agent calls `memory_search`, three sources are queried in parallel:
+### Auto-capture
 
-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
+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.
 
-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
-```
+### Persistent connection
 
-To mark complete, update:
-
-```yaml
-status: done
-```
+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.
 
-Done tasks are filtered out of the `Active Tasks` section in composited `memory_search`.
+## Agent tools
 
-### 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
+All tools accept an optional `project` parameter for cross-project operations.
 
-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.
+| 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 |
 
-### 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)
-
-## Agent Tools
-
-All content tools accept an optional `project` parameter to operate on a different project than the default (cross-project operations).
-
-### `list_workspaces`
-List all workspaces (personal and organization) accessible to this user.
-```
-list_workspaces()
-```
-
-### `list_memory_projects`
-List all projects, optionally filtered by workspace.
-```
-list_memory_projects()
-list_memory_projects(workspace="my-org")
-```
-
-### `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 |
+| `/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
-```
-
-### 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:
+## Bundled skills
 
-- `integration/bm-client.integration.test.ts`
+Six skills ship with the plugin — no installation needed:
 
-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.
+- **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
 
-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
-
-# 4) Publish current version from package.json
-just release-publish
-```
+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.
 
-For a full release (version bump + publish + push tag):
+## Troubleshooting
 
-```bash
-just release patch   # or: minor, major, 0.2.0, etc.
-```
+**`bm` not found** — Install uv, then restart the gateway. Or install manually: `uv tool install basic-memory`
 
-### GitHub Actions CI/CD
+**Search returns nothing** — Check that Basic Memory connected (look for `connected to BM` in logs). Verify files exist in the project directory.
 
-- 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
+**Jiti cache issues** — `rm -rf /tmp/jiti/ "$TMPDIR/jiti/"` then restart the gateway.
 
-Repository secret required:
+**Disable semantic search** — Set `BASIC_MEMORY_SEMANTIC_SEARCH_ENABLED=false` to fall back to full-text only.
 
-- `NPM_TOKEN` (npm publish token with package publish permissions)
+## 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)
 
-## License
+## Telemetry
 
-MIT — see LICENSE file.
+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.
 
-## Links
+## License
 
-- [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

@@ -196,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") ||
@@ -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)
@@ -829,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,
@@ -854,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
@@ -137,7 +114,7 @@ export function parseConfig(raw: unknown): BasicMemoryConfig {
     projectPath:
       typeof cfg.projectPath === "string" && cfg.projectPath.length > 0
         ? cfg.projectPath
-        : memoryDir,
+        : ".",
     bmPath:
       typeof cfg.bmPath === "string" && cfg.bmPath.length > 0
         ? cfg.bmPath
@@ -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,4 +1,5 @@
-import type { Server } from "node:http"
+import { execSync } from "node:child_process"
+
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
 import { BmClient } from "./bm-client.ts"
 import { registerCli } from "./commands/cli.ts"
@@ -9,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"
@@ -82,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
@@ -97,45 +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}`,
-            )
-          })
-        }
-
         log.info("connected — BM MCP stdio session running")
       },
       stop: async () => {
         log.info("stopping BM MCP session...")
-        if (dashboardServer) {
-          await new Promise<void>((resolve) =>
-            dashboardServer?.close(() => resolve()),
-          )
-          dashboardServer = undefined
-          log.info("dashboard stopped")
-        }
         await client.stop()
         log.info("stopped")
       },

package/openclaw.plugin.json

@@ -48,19 +48,14 @@
     },
     "projectPath": {
       "label": "Project Path",
-      "placeholder": "~/.openclaw/workspace/memory/",
-      "help": "Filesystem path for Basic Memory project data (relative paths resolve from workspace); created automatically if missing",
+      "placeholder": ".",
+      "help": "Filesystem path for Basic Memory project data (defaults to workspace root; relative paths resolve from workspace)",
       "advanced": true
     },
     "cloud": {
       "label": "Cloud Backend",
       "help": "Optional cloud backend config (url + api_key). If present, uses cloud instead of local BM.",
       "advanced": true
-    },
-    "dashboard": {
-      "label": "Dashboard",
-      "help": "Web dashboard for visualizing the knowledge graph (enabled, port)",
-      "advanced": true
     }
   },
   "configSchema": {
@@ -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.8",
+  "version": "0.1.1",
   "type": "module",
   "description": "Basic Memory plugin for OpenClaw — local-first knowledge graph for agent memory",
   "license": "MIT",
@@ -33,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/scripts/setup-bm.sh

@@ -15,11 +15,10 @@ if ! command -v uv >/dev/null 2>&1; then
   exit 0
 fi
 
-# ── install basic-memory[semantic] ────────────────────────────────
+# ── install basic-memory ────────────────────────────────
 echo "Installing basic-memory from ${BM_REPO}@${BM_REF} ..."
 uv tool install \
-  "basic-memory[semantic] @ git+${BM_REPO}@${BM_REF}" \
-  --with 'onnxruntime<1.24; platform_system == "Darwin" and platform_machine == "x86_64"' \
+  "basic-memory @ git+${BM_REPO}@${BM_REF}" \
   --force
 
 # ── verify ────────────────────────────────────────────────────────