@nowledge/openclaw-nowledge-mem 0.6.8 → 0.6.12

package/CHANGELOG.md

@@ -2,6 +2,46 @@
 
 All notable changes to the Nowledge Mem OpenClaw plugin will be documented in this file.
 
+## [0.6.12] - 2026-03-15
+
+### Added
+
+- **Agent behavioral skill**: the plugin now registers a `skills/memory-guide/SKILL.md` skill via the OpenClaw manifest `skills[]` array. OpenClaw auto-discovers it and presents it to the agent as an available skill. The skill teaches the agent when and how to search, save, explore connections, browse timelines, fetch past conversations, and use Working Memory. This is the single biggest change for memory recall quality: agents now receive structured guidance before their first memory interaction, rather than relying on tool descriptions alone.
+
+### Changed
+
+- **Behavioral guidance is now directive**: the always-on system hint now says "Before answering questions about prior work, decisions, dates, people, preferences, or plans: search with memory_search" instead of the previous "When prior context would improve your response, search." This matches the imperative pattern that LLMs follow most reliably, and explicitly notes "natural language queries, not file paths" to prevent confusion with OpenClaw's built-in file-based memory guidance.
+
+## [0.6.11] - 2026-03-15
+
+### Changed
+
+- **Release-cycle alignment**: the OpenClaw plugin version now tracks the main Nowledge Mem `0.6.11` release line, so the published plugin and app-facing changelog stay in sync for this release.
+- **Agent-assisted onboarding added**: the plugin now ships with a bundled `SKILL.md` playbook so AI agents can install, configure, verify, and explain the integration without collapsing the human docs into an agent script.
+- **Aligned command execution with OpenClaw runtime**: the plugin now runs `nmem` through OpenClaw's runtime command runner instead of importing `child_process` directly. This removes gateway-blocking synchronous process calls from the plugin surface and matches current OpenClaw plugin abstractions.
+- **Static guidance moved into system-prompt space**: the always-on behavioral hint now uses system-context injection instead of user-prompt prepend text, matching OpenClaw's newer `prependSystemContext` / `appendSystemContext` guidance for cacheable stable instructions.
+- **Minimum supported OpenClaw version is now `2026.3.7`**: this is the first release with the system-context fields the plugin now relies on.
+- **Package publishing is now explicit**: npm contents are pinned through the package manifest instead of relying on `.gitignore` fallback behavior, making releases more deterministic.
+
+### Fixed
+
+- **Health checks now keep the JSON contract**: the internal `status` probe now uses `--json`, matching the rest of the plugin's parseable CLI surface.
+- **Resolved config now overrides inherited `NMEM_*` values cleanly**: child-process env construction now clears inherited `NMEM_API_URL` and `NMEM_API_KEY` before applying the effective plugin config, so local mode cannot accidentally inherit a stale remote backend.
+- **Failure logs no longer echo full CLI argv**: plugin logs now record a sanitized command label instead of raw `nmem` arguments, avoiding retention of user queries or message batches in log files.
+- **Thread CLI flag drift**: thread search and thread fetch now use `-n`, matching the current `nmem` thread CLI surface and the plugin's own internal docs.
+- **Install and trust docs now match current OpenClaw behavior**: the docs now explain that `openclaw plugins install` enables the plugin and selects the memory slot automatically, and they document the recommended `plugins.allow` hardening path for non-bundled plugins.
+- **Default-mode docs no longer over-promise auto-injected context**: Working Memory and recalled memories are now described as opt-in `sessionContext` behavior, not something every default install gets automatically.
+
+## [0.6.9] - 2026-03-05
+
+### Fixed
+
+- **Auto-recall searched with full prompt instead of user message**: `event.prompt` contains the entire conversation history (system prompt + all prior turns), making recalled memories irrelevant as conversation grows. Now uses a tiered query strategy: substantial messages (>=40 chars) search alone; short messages (3-39 chars, likely follow-ups like "explain that more") include the last 3 messages as context for topic grounding; tiny messages (<3 chars) skip recall. Falls back to truncated `event.prompt` (500 chars) only when `event.messages` is unavailable.
+
+### Added
+
+- **`recallMinScore` config option** (0-100, default 0): Minimum relevance score threshold for auto-recalled memories. Set to e.g. 30 to filter out low-confidence results. Configurable via OpenClaw Config UI, config file, or `NMEM_RECALL_MIN_SCORE` env var.
+
 ## [0.6.8] - 2026-02-27
 
 ### Changed

package/CLAUDE.md

@@ -7,7 +7,8 @@ Continuation guide for `community/nowledge-mem-openclaw-plugin`.
 - Plugin target: OpenClaw plugin runtime (memory slot provider)
 - Runtime: JS ESM modules under `src/`, no TS build pipeline
 - Memory backend: `nmem` CLI (fallback: `uvx --from nmem-cli nmem`)
-- Architecture: **CLI-first** - all operations go through the nmem CLI, not direct API calls
+- OpenClaw minimum: `2026.3.7` (`appendSystemContext` / system-context guidance required)
+- Architecture: **CLI-first via OpenClaw runtime** - all CLI execution goes through `api.runtime.system.runCommandWithTimeout`, not direct `child_process`
 - Remote mode: set `NMEM_API_URL` + `NMEM_API_KEY` env vars or config file `apiUrl` + `apiKey`
 
 ## Design Philosophy
@@ -27,7 +28,8 @@ Reflects Nowledge Mem's genuine v0.6 strengths:
 ```
 src/
   index.js          - plugin registration (tools, hooks, commands, CLI)
-  client.js         - CLI wrapper with API fallback; credential handling
+  client.js         - CLI wrapper with API fallback; async runtime command execution; credential handling
+  spawn-env.js      - env-only credential injection for the nmem runner
   config.js         - config cascade: ~/.nowledge-mem/openclaw.json > pluginConfig > env vars > defaults
   hooks/
     behavioral.js   - always-on behavioral guidance (~50 tokens/turn)
@@ -43,7 +45,10 @@ src/
     forget.js           - memory deletion by ID or search
     thread-search.js    - search past conversations by keyword
     thread-fetch.js     - fetch full messages from a thread with pagination
-openclaw.plugin.json - manifest + config schema (version, uiHints, configSchema)
+skills/
+  memory-guide/
+    SKILL.md            - agent behavioral skill: when/how to search, save, explore memory (auto-discovered by OpenClaw)
+openclaw.plugin.json - manifest + config schema (version, uiHints, configSchema, skills)
 ~/.nowledge-mem/openclaw.json - optional user config file (overrides OpenClaw settings when present)
 ```
 
@@ -62,15 +67,19 @@ openclaw.plugin.json - manifest + config schema (version, uiHints, configSchema)
 
 ### Thread Tools (progressive conversation retrieval)
 - `nowledge_mem_thread_search` - search past conversations by keyword. Returns threads with matched message snippets, relevance scores, and message counts. Supports `source` filter.
-- `nowledge_mem_thread_fetch` - fetch full messages from a specific thread. Supports pagination via `offset` + `limit` for progressive retrieval of long conversations.
+- `nowledge_mem_thread_fetch` - fetch messages from a specific thread. Start with a small page, then use `offset` + `limit` for progressive retrieval only when more context is needed.
 
 ### Diagnostics
 - `nowledge_mem_status` - show effective config (mode, apiUrl, apiKey set, sessionContext, sessionDigest, etc.), backend connectivity, and version. No parameters.
 
+## Skill Surface
+
+- `skills/memory-guide/SKILL.md` - agent behavioral skill auto-discovered by OpenClaw via manifest `skills[]`. Teaches the agent when/how to search, save, explore connections, fetch threads, and use Working Memory. Read on-demand when the agent identifies a memory-related task.
+
 ## Hook Surface
 
-- `before_prompt_build` (always-on) - behavioral guidance: brief note telling agent to save/search proactively. Adjusts when sessionContext is on to avoid redundant searches.
-- `before_prompt_build` (sessionContext) - session context: Working Memory + `searchRich()` with `relevanceReason` in context
+- `before_prompt_build` (always-on) - directive behavioral guidance in system-prompt space: tells agent to search before answering questions about prior work/decisions/preferences, and to save decisions/learnings proactively. Explicitly notes semantic search (not file paths) to counter OpenClaw's hardcoded memory section. Adjusts when sessionContext is on to avoid redundant searches.
+- `before_prompt_build` (sessionContext) - session context: Working Memory + `searchRich()` memories with `relevanceReason`. Note: does NOT inject thread snippets — threads are available via `memory_search` tool and `nowledge_mem_thread_fetch`.
 - `agent_end` - thread capture + LLM triage/distillation (requires `sessionDigest: true`)
 - `after_compaction` - thread append
 - `before_reset` - thread append
@@ -91,6 +100,7 @@ Optional config file at `~/.nowledge-mem/openclaw.json`. Falls through to OpenCl
 | `sessionDigest` | boolean | `true` | `NMEM_SESSION_DIGEST` | Thread capture + LLM distillation at session end |
 | `digestMinInterval` | integer 0-86400 | `300` | `NMEM_DIGEST_MIN_INTERVAL` | Minimum seconds between session digests |
 | `maxContextResults` | integer 1-20 | `5` | `NMEM_MAX_CONTEXT_RESULTS` | How many memories to inject at prompt time |
+| `recallMinScore` | integer 0-100 | `0` | `NMEM_RECALL_MIN_SCORE` | Min relevance score (%) to include in auto-recall |
 | `apiUrl` | string | `""` | `NMEM_API_URL` | Remote server URL. Empty = local (127.0.0.1:14242) |
 | `apiKey` | string | `""` | `NMEM_API_KEY` | API key. Never logged. |
 
@@ -120,8 +130,8 @@ Legacy aliases accepted silently in all sources for backward compat:
 | `nmem --json wm patch --heading "## S" --content/--append` | `client.patchWorkingMemory()` | Section-level WM update |
 | `nmem --json m delete <id>` | `client.execJson()` in forget.js | Delete |
 | `GET /threads/search?query=&limit=` | `client.searchThreads()` | Thread search enrichment (best-effort, API-only) |
-| `nmem --json t search <q> --limit N` | `client.searchThreadsFull()` | Full thread search (CLI-first, API fallback) |
-| `nmem --json t show <id> --limit N --offset O` | `client.fetchThread()` | Fetch thread messages with pagination |
+| `nmem --json t search <q> -n N` | `client.searchThreadsFull()` | Full thread search (CLI-first, API fallback) |
+| `nmem --json t show <id> -n N --offset O` | `client.fetchThread()` | Fetch thread messages with pagination |
 
 All commands have API fallback for older CLI versions.
 

package/README.md

@@ -2,12 +2,14 @@
 
 Local-first knowledge graph memory for [OpenClaw](https://openclaw.ai) agents, powered by [Nowledge Mem](https://mem.nowledge.co).
 
-Your AI tools forget. We remember. Everywhere. This plugin gives your OpenClaw agents persistent, graph-connected memory across WhatsApp, Telegram, Discord, Slack, and every channel OpenClaw supports. All data stays on your machine.
+Your AI tools forget. We remember. Everywhere. This plugin gives OpenClaw both lossless session memory and the same graph-connected memory layer your other AI tools can use too. Every OpenClaw conversation is captured as a searchable thread, important moments can distill into linked memories with `sourceThreadId`, and knowledge from Claude, Cursor, web chats, and imported threads stays searchable inside OpenClaw. Local-first by default, with remote mode when you want a shared server.
+
+This is not a flat note store. Nowledge Mem links related knowledge into a graph, tracks how ideas evolve, deduplicates repeated context, and can run background intelligence to produce daily briefings, contradiction checks, and crystals from converging evidence. OpenClaw can search that same growing memory layer instead of starting from scratch every time.
 
 ## Requirements
 
 - [Nowledge Mem](https://mem.nowledge.co) desktop app **or** `nmem` CLI
-- [OpenClaw](https://openclaw.ai) >= 2026.1.29
+- [OpenClaw](https://openclaw.ai) >= 2026.3.7
 
 ## Installation
 
@@ -15,9 +17,37 @@ Your AI tools forget. We remember. Everywhere. This plugin gives your OpenClaw a
 openclaw plugins install @nowledge/openclaw-nowledge-mem
 ```
 
-### Local mode (default)
+OpenClaw's installer writes the install record, enables the plugin, and switches the `memory` slot to `openclaw-nowledge-mem`. Restart OpenClaw after install to load it.
+
+### Agent-assisted setup
+
+If another AI agent is helping you install this plugin, point it at the bundled [SKILL.md](./SKILL.md).
+
+Copyable instruction:
+
+```text
+Read https://raw.githubusercontent.com/nowledge-co/community/main/nowledge-mem-openclaw-plugin/SKILL.md and follow it to install, configure, verify, and explain Nowledge Mem for OpenClaw.
+```
+
+That guide is written for AI agents, not for humans. It handles local vs remote mode, optional API auth, trust pinning, restart, verification, and next steps.
+
+### Recommended hardening
 
-Start Nowledge Mem desktop app or run `nmem serve`, then enable the plugin:
+If you keep non-bundled plugins on an explicit trust allowlist, add:
+
+```json
+{
+  "plugins": {
+    "allow": ["openclaw-nowledge-mem"]
+  }
+}
+```
+
+`plugins.allow` is id-based, not source-based. If you also use `plugins.load.paths` or `openclaw plugins install --link`, review those paths too. An allowlist trusts the active plugin with that id; it does not pin where it came from.
+
+### Manual config or verification
+
+If you manage config manually, or you want to verify what the installer selected, this is the expected shape:
 
 ```json
 {
@@ -32,7 +62,7 @@ Start Nowledge Mem desktop app or run `nmem serve`, then enable the plugin:
 }
 ```
 
-That's it. The agent gets 10 tools and calls them on demand. No extra tokens wasted.
+By default the agent gets 10 tools on demand, a behavioral skill that teaches it when to search and save, a short always-on system hint, and end-of-session capture. Working Memory injection is optional and controlled by `sessionContext`.
 
 ### Remote mode
 
@@ -51,6 +81,11 @@ Or use a config file at `~/.nowledge-mem/openclaw.json`:
 
 The `apiKey` is injected as `NMEM_API_KEY` into the nmem CLI process. Never passed as a CLI argument, never logged.
 
+### Configure via WebUI of OpenClaw
+
+<img width="1192" height="2007" alt="openclaw-config" src="https://github.com/user-attachments/assets/a4abd855-db56-4a1f-b0ac-0114909d0c20" />
+
+
 ## How It Works
 
 ### Per-Turn Flow
@@ -61,7 +96,7 @@ Every user message triggers hooks before the agent sees it, then the agent decid
 flowchart TD
     A["User sends message"] --> B["before_prompt_build hook"]
 
-    B --> C["Behavioral guidance(always, ~110 tokens)"]
+    B --> C["Behavioral guidance(cacheable system hint)"]
     B -.->|"sessionContext: true"| D["Working Memory +relevant memories (~1-2 KB)"]
 
     C --> E["Agent processes message(10 tools available)"]
@@ -80,7 +115,7 @@ flowchart TD
 
 ### When Each Tool Gets Called
 
-The behavioral hook nudges the agent to **search before answering** and **save after deciding**. Here's when each tool fires:
+The behavioral skill and always-on hook nudge the agent to **search before answering** and **save after deciding**. Here's when each tool fires:
 
 | Scenario | Tool | What happens |
 |----------|------|--------------|
@@ -155,7 +190,7 @@ Two entry points:
 flowchart LR
     subgraph "default" ["Default (recommended)"]
         direction TB
-        D1["Every turn: behavioral guidance (~50 tokens)"]
+        D1["Every turn: short system hint"]
         D2["Agent calls 10 tools on demand"]
         D3["Session end: thread capture + LLM distillation"]
     end
@@ -169,7 +204,7 @@ flowchart LR
 
     subgraph minimal ["Minimal"]
         direction TB
-        M1["Every turn: behavioral guidance (~50 tokens)"]
+        M1["Every turn: short system hint"]
         M2["Agent calls 10 tools on demand"]
         M3["No automatic capture"]
     end
@@ -257,14 +292,14 @@ The plugin supports three modes. Choose based on how much you want to guarantee
 
 | Mode | Config | Behavior | Tradeoff |
 |------|--------|----------|----------|
-| **Default** (recommended) | `sessionContext: false, sessionDigest: true` | Agent calls 10 tools on demand. Behavioral guidance every turn (~50 tokens). Conversations captured + distilled at session end. | Lowest cost. Agent decides when to search, usually smart, occasionally forgets. |
-| **Session context** | `sessionContext: true` | Working Memory + relevant memories injected at prompt time, plus all 10 tools still available. | ~1-2 KB/turn. Guarantees context is always present. Best for short sessions or critical workflows. |
-| **Minimal** | `sessionDigest: false` | Tool-only, no automatic capture. | Zero overhead beyond guidance. Use when you handle memory manually. |
+| **Default** (recommended) | `sessionContext: false, sessionDigest: true` | Agent calls 10 tools on demand. A short system hint stays on. Conversations captured + distilled at session end. | Lowest overhead. Agent decides when to search, usually smart, occasionally forgets. |
+| **Session context** | `sessionContext: true` | Working Memory + relevant memories injected at prompt time, plus all 10 tools still available. | Higher per-turn context cost. Guarantees context is present from the first turn. |
+| **Minimal** | `sessionDigest: false` | Tool-only, no automatic capture. | Small overhead from the always-on hint only. Use when you handle memory manually. |
 
 **Which mode should you use?**
 
 - **Most users**: start with default. The agent gets behavioral guidance nudging it to search before answering and save after deciding. It works well for most conversations.
-- **Short sessions or critical accuracy**: enable `sessionContext`. This guarantees relevant memories are present from the first turn. The agent doesn't need to decide whether to search. The tradeoff is ~1-2 KB of context per turn.
+- **Short sessions or critical accuracy**: enable `sessionContext`. This guarantees relevant memories are present from the first turn. The agent doesn't need to decide whether to search. The tradeoff is a larger per-turn prompt.
 - **Full manual control**: set `sessionDigest: false`. You control what gets saved (via `/remember` or `nowledge_mem_save`) and nothing is captured automatically.
 
 ### Session Context (`sessionContext`, default: false)
@@ -287,7 +322,7 @@ Honest answers to common questions about how the memory system works.
 
 **Does the agent always search before answering?**
 
-No. The behavioral guidance nudges the agent to search, but doesn't force it. This is a deliberate tradeoff: forcing a search on every turn would add latency and cost for messages that don't need past context (like "hello" or "thanks"). In practice, modern LLMs follow behavioral guidance reliably for knowledge-related questions. If guaranteed recall matters for your use case, enable `sessionContext: true`. That injects relevant memories at prompt time, before the agent even processes your message.
+The plugin uses two layers to drive recall. First, a behavioral skill (auto-discovered by OpenClaw) teaches the agent when and how to use memory tools. Second, a short always-on system hint reminds it to "search before answering questions about prior work, decisions, dates, people, preferences, or plans." In practice, modern LLMs follow this directive guidance reliably for knowledge-related questions. For messages that don't need past context (like "hello" or "thanks"), the agent skips the search, which is the right tradeoff. If guaranteed recall matters for your use case, enable `sessionContext: true`. That injects relevant memories at prompt time, before the agent even processes your message.
 
 **What stops the agent from saving duplicate memories?**
 
@@ -322,7 +357,7 @@ openclaw nowledge-mem status
 
 ## Configuration
 
-No config needed to get started. The defaults work for local mode.
+No config is required for a normal npm install. The defaults work for local mode, and `openclaw plugins install` already enables the plugin and selects the memory slot.
 
 To change settings, use the OpenClaw plugin settings UI. Changes take effect on restart.
 
@@ -332,6 +367,7 @@ To change settings, use the OpenClaw plugin settings UI. Changes take effect on
 | `sessionDigest` | boolean | `true` | Thread capture + LLM distillation at session end |
 | `digestMinInterval` | integer | `300` | Minimum seconds between session digests for the same thread (0-86400) |
 | `maxContextResults` | integer | `5` | Max memories to inject at prompt time (1-20, only used when sessionContext is enabled) |
+| `recallMinScore` | integer | `0` | Min relevance score (0-100%) to include in auto-recall. 0 = include all |
 | `apiUrl` | string | `""` | Remote server URL. Empty = local (`http://127.0.0.1:14242`) |
 | `apiKey` | string | `""` | API key for remote access. Injected as `NMEM_API_KEY` env var, never logged |
 
@@ -345,6 +381,7 @@ For persistent or scripted config, create `~/.nowledge-mem/openclaw.json`:
   "sessionDigest": true,
   "digestMinInterval": 300,
   "maxContextResults": 5,
+  "recallMinScore": 0,
   "apiUrl": "",
   "apiKey": ""
 }
@@ -361,6 +398,7 @@ NMEM_SESSION_CONTEXT=true
 NMEM_SESSION_DIGEST=true
 NMEM_DIGEST_MIN_INTERVAL=300
 NMEM_MAX_CONTEXT_RESULTS=5
+NMEM_RECALL_MIN_SCORE=0
 NMEM_API_URL=https://...
 NMEM_API_KEY=your-key
 ```
@@ -373,6 +411,20 @@ config file > OpenClaw settings > env vars > defaults
 
 Use `nowledge_mem_status` (or `openclaw nowledge-mem status`) to see where each value comes from.
 
+### Trust warning after install
+
+If OpenClaw logs a warning like `plugins.allow is empty; discovered non-bundled plugins may auto-load`, the plugin is installed correctly. OpenClaw is warning that you have not pinned trust for non-bundled plugins yet. Add:
+
+```json
+{
+  "plugins": {
+    "allow": ["openclaw-nowledge-mem"]
+  }
+}
+```
+
+If you also use linked or workspace copies, review `plugins.load.paths` before relying on an allowlist. OpenClaw allowlists plugin ids, not install provenance.
+
 ## What Makes This Different
 
 - **Local-first**: no API key, no cloud account. Your knowledge stays on your machine.

package/SKILL.md

@@ -0,0 +1,245 @@
+# Nowledge Mem for OpenClaw
+
+Use this guide when an AI agent is helping a user install, configure, verify, or explain the Nowledge Mem OpenClaw plugin.
+
+Nowledge Mem is not just "memory for OpenClaw." It is the user's shared memory layer across OpenClaw, Claude Code, Cursor, browser capture, imported threads, and documents. OpenClaw joins that context exchange.
+
+## Use This When
+
+- The user wants to install or configure the OpenClaw plugin
+- The user wants OpenClaw to connect to existing Nowledge Mem data
+- The user wants local-first memory on this machine
+- The user wants remote or multi-machine memory through a remote `apiUrl`
+- The user wants to verify that OpenClaw can recall, save, and search memory
+
+## Do Not Use This When
+
+- The user only wants temporary context in the current OpenClaw session
+- The user is troubleshooting unrelated OpenClaw issues
+- The user only wants direct MCP setup for another client
+
+## Product Framing
+
+When talking to users:
+
+- Say "Nowledge Mem gives OpenClaw the same shared memory your other AI tools can use."
+- Lead with cross-tool continuity, not with plugin internals.
+- For local mode, say "No API key is needed for local mode."
+- For remote mode, say "Set `apiUrl`, and add `apiKey` when the server requires auth."
+- Do not imply that OpenClaw is the only source of truth. It is one client of the user's larger memory system.
+- Do not imply that cloud backup is the default. Our default story is local-first.
+
+Good user-facing explanation:
+
+> OpenClaw can now read the same memory you already built in your other AI tools, and what happens in OpenClaw can enrich that shared memory too.
+
+## Definition of Done
+
+This task is not complete until all of the following are true:
+
+1. `nmem` is available
+2. The intended backend is verified reachable with `nmem`
+3. The OpenClaw plugin is installed
+4. OpenClaw is using the Nowledge Mem memory slot
+5. Remote config is written only if the user chose remote mode
+6. OpenClaw is restarted
+7. `openclaw nowledge-mem status` succeeds
+8. The user receives a short handoff covering:
+   - one real first question to ask
+   - how to bring in older history
+   - local vs remote expectations
+   - trust pinning if they see `plugins.allow` warnings
+
+## Setup Flow
+
+### Step 0 — Choose Local or Remote
+
+Ask the user which setup they want:
+
+1. Local Nowledge Mem already running on this machine
+2. Existing remote Nowledge Mem server
+
+Explain the difference plainly:
+
+- Local mode: OpenClaw talks to the local Nowledge Mem app/server through `nmem`
+- Remote mode: OpenClaw talks to a remote Nowledge Mem server through `nmem --api-url ...`; add `apiKey` when that server has auth enabled
+
+### Step 1 — Verify `nmem`
+
+```bash
+nmem --version
+```
+
+If this fails:
+
+- For users with the desktop app, direct them to **Settings > Preferences > Developer Tools > Install CLI**
+- Otherwise suggest `pip install nmem-cli`
+
+### Step 2 — Verify the Backend Before Plugin Setup
+
+Local mode:
+
+```bash
+nmem --json status
+```
+
+Remote mode without auth:
+
+```bash
+nmem --json --api-url "$API_URL" status
+```
+
+Remote mode with auth:
+
+```bash
+NMEM_API_KEY="$API_KEY" nmem --json --api-url "$API_URL" status
+```
+
+Success means the backend responds correctly through `nmem`. Do not skip this step and assume the URL/auth is right.
+
+### Step 3 — Install the Plugin
+
+Default install:
+
+```bash
+openclaw plugins install @nowledge/openclaw-nowledge-mem
+```
+
+If the user is on mainland China or npmjs is unusually slow, prefer a one-shot mirror override instead of changing global npm config:
+
+```bash
+NPMJS_TIME="$(curl -o /dev/null -sS --connect-timeout 2 --max-time 6 -w '%{time_total}' https://registry.npmjs.org/@nowledge%2fopenclaw-nowledge-mem || echo timeout)"
+MIRROR_TIME="$(curl -o /dev/null -sS --connect-timeout 2 --max-time 6 -w '%{time_total}' https://registry.npmmirror.com/@nowledge%2fopenclaw-nowledge-mem || echo timeout)"
+
+if [ "$MIRROR_TIME" != "timeout" ] && { [ "$NPMJS_TIME" = "timeout" ] || awk "BEGIN { exit !($NPMJS_TIME > 2 && $MIRROR_TIME < $NPMJS_TIME) }"; }; then
+  NPM_CONFIG_REGISTRY=https://registry.npmmirror.com openclaw plugins install @nowledge/openclaw-nowledge-mem
+else
+  openclaw plugins install @nowledge/openclaw-nowledge-mem
+fi
+```
+
+Important facts:
+
+- The installer already writes the install record
+- The installer already enables the plugin
+- The installer already switches the `memory` slot to `openclaw-nowledge-mem`
+
+Do not tell the user to hand-edit those settings unless they are using a manual/path setup.
+
+### Step 4 — Configure Remote Only When Needed
+
+Local mode:
+
+- No extra config is required
+
+Remote mode:
+
+- Prefer setting `apiUrl` and `apiKey` in the OpenClaw plugin settings
+- Use `~/.nowledge-mem/openclaw.json` only when the user wants a stable machine-local override or scripted setup
+
+`~/.nowledge-mem/openclaw.json` example:
+
+```json
+{
+  "apiUrl": "https://nowledge.example.com",
+  "apiKey": "your-api-key-here"
+}
+```
+
+Important precedence rule:
+
+- `~/.nowledge-mem/openclaw.json` overrides OpenClaw plugin settings
+- Then plugin settings override inherited environment variables
+- Do not assume stale `NMEM_API_URL` or `NMEM_API_KEY` env vars should keep winning
+
+If the remote server does not require auth, omit `apiKey`.
+
+### Step 5 — Pin Trust When Appropriate
+
+If OpenClaw warns that `plugins.allow` is empty, or the user wants explicit trust for non-bundled plugins, add:
+
+```json
+{
+  "plugins": {
+    "allow": ["openclaw-nowledge-mem"]
+  }
+}
+```
+
+Explain this correctly:
+
+- `plugins.allow` trusts the plugin id
+- It does not pin the plugin source path
+- If the user also has linked or workspace copies in `plugins.load.paths`, they should review those too
+
+### Step 6 — Restart OpenClaw
+
+Restart OpenClaw so the plugin and hooks are active.
+
+If an agent is doing the restart automatically, tell the user before triggering it.
+
+### Step 7 — Verify the Plugin
+
+First check the plugin status:
+
+```bash
+openclaw nowledge-mem status
+```
+
+Then verify in chat.
+
+For a clean synthetic check:
+
+1. `/remember We chose PostgreSQL for task events`
+2. `/recall PostgreSQL`
+3. `/new`
+4. Ask `What database did we choose for task events?`
+
+If the user already has real memory in Nowledge Mem, prefer a real question over a synthetic demo. Good examples:
+
+- `What was I working on this week?`
+- `What did we already decide about the task API?`
+- `Find the conversation where we discussed Redis caching`
+
+## Handoff Message
+
+After setup succeeds, send a short handoff that covers all four points:
+
+1. OpenClaw is now connected
+2. The best next question to ask
+3. How to bring in older history
+4. What the local/remote trust model is
+
+Good structure:
+
+```text
+OpenClaw is now connected to Nowledge Mem.
+
+Try this next:
+- Ask OpenClaw: "What was I working on this week?"
+
+If you want more history:
+- Import old AI threads or browser-captured chats into Nowledge Mem so OpenClaw can search them too.
+
+What to expect:
+- Local mode needs no API key.
+- Remote mode uses the same apiUrl and, when auth is enabled, the same apiKey you already verified with nmem.
+- If OpenClaw warns that plugins.allow is empty, add openclaw-nowledge-mem to the allowlist to pin trust explicitly.
+```
+
+## Troubleshooting
+
+| Symptom | What to do |
+| --- | --- |
+| `nmem --json status` fails in local mode | Start Nowledge Mem locally first |
+| Remote mode fails | Re-run `nmem --json --api-url ... status` with the exact URL and auth you plan to use |
+| `openclaw nowledge-mem status` fails after install | Restart OpenClaw and confirm the plugin was installed successfully |
+| `plugins.allow is empty` warning | Add `openclaw-nowledge-mem` to `plugins.allow` if the user wants explicit trust |
+| Remote config seems ignored | Check whether `~/.nowledge-mem/openclaw.json` is overriding plugin settings |
+| Local mode unexpectedly talks to a remote server | Check for stale `NMEM_API_URL` / `NMEM_API_KEY` in the environment or an overriding `~/.nowledge-mem/openclaw.json` |
+
+## Notes for Agents
+
+- Human docs and AI setup instructions are different things. Keep the human explanation short and concrete.
+- Do not dump the whole configuration model on the user up front.
+- Do not reduce Nowledge Mem to "OpenClaw memory." The real value is shared context across tools and growth of knowledge over time.

package/openclaw.plugin.json

@@ -1,15 +1,16 @@
 {
 	"id": "openclaw-nowledge-mem",
-	"version": "0.6.8",
+	"version": "0.6.12",
 	"kind": "memory",
+	"skills": ["skills/memory-guide"],
 	"uiHints": {
 		"sessionContext": {
 			"label": "Session context injection",
-			"help": "Inject Working Memory and relevant memories at prompt time. Off by default \u2014 the agent can call memory_search on demand instead."
+			"help": "Inject Working Memory and relevant memories at prompt time. Off by default; the agent can call memory_search on demand instead."
 		},
 		"sessionDigest": {
 			"label": "Session digest at end",
-			"help": "Capture conversation threads and distill key memories via LLM at session end. On by default \u2014 negligible cost, one triage call per session."
+			"help": "Capture conversation threads and distill key memories via LLM at session end. On by default. Negligible cost, one triage call per session."
 		},
 		"digestMinInterval": {
 			"label": "Minimum digest interval (seconds)",
@@ -17,7 +18,11 @@
 		},
 		"maxContextResults": {
 			"label": "Max context results",
-			"help": "How many memories to inject for each context cycle (1\u201320)"
+			"help": "How many memories to inject for each context cycle (1-20)"
+		},
+		"recallMinScore": {
+			"label": "Min recall score (%)",
+			"help": "Only inject memories with relevance score above this threshold (0-100). Set to 0 to include all results."
 		},
 		"apiUrl": {
 			"label": "Server URL (remote mode)",
@@ -25,7 +30,7 @@
 		},
 		"apiKey": {
 			"label": "API key (remote mode)",
-			"help": "Required when connecting to a remote server. Never logged or passed as a CLI argument \u2014 injected as NMEM_API_KEY env var only.",
+			"help": "Required when connecting to a remote server. Never logged or passed as a CLI argument. Injected as NMEM_API_KEY env var only.",
 			"secret": true
 		}
 	},
@@ -35,7 +40,7 @@
 			"sessionContext": {
 				"type": "boolean",
 				"default": false,
-				"description": "Inject Working Memory and recalled memories at prompt time. Off by default \u2014 the agent queries memory on demand via tools."
+				"description": "Inject Working Memory and recalled memories at prompt time. Off by default; the agent queries memory on demand via tools."
 			},
 			"sessionDigest": {
 				"type": "boolean",
@@ -56,6 +61,13 @@
 				"maximum": 20,
 				"description": "Maximum memories to inject at prompt time (only used when sessionContext is enabled)"
 			},
+			"recallMinScore": {
+				"type": "integer",
+				"default": 0,
+				"minimum": 0,
+				"maximum": 100,
+				"description": "Minimum relevance score (0-100%) to include a memory in auto-recall. Set to 0 to include all results."
+			},
 			"apiUrl": {
 				"type": "string",
 				"default": "",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nowledge/openclaw-nowledge-mem",
-	"version": "0.6.8",
+	"version": "0.6.12",
 	"type": "module",
 	"description": "Nowledge Mem memory plugin for OpenClaw, local-first personal knowledge base",
 	"author": {
@@ -14,6 +14,15 @@
 		"url": "https://github.com/nowledge-co/community.git",
 		"directory": "nowledge-mem-openclaw-plugin"
 	},
+	"files": [
+		"src",
+		"skills",
+		"README.md",
+		"CHANGELOG.md",
+		"CLAUDE.md",
+		"SKILL.md",
+		"openclaw.plugin.json"
+	],
 	"openclaw": {
 		"extensions": ["./src/index.js"]
 	},
@@ -23,7 +32,7 @@
 		"format": "biome format --write ."
 	},
 	"peerDependencies": {
-		"openclaw": ">=2026.1.29"
+		"openclaw": ">=2026.3.7"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "^1.9.0"