@nowledge/openclaw-nowledge-mem 0.6.9 → 0.6.13

package/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 All notable changes to the Nowledge Mem OpenClaw plugin will be documented in this file.
 
+## [0.6.13] - 2026-03-17
+
+### Fixed
+
+- **Dashboard config: API key field now masked correctly.** The manifest `uiHints` for `apiKey` used `"secret": true` but OpenClaw's `PluginConfigUiHint` type expects `"sensitive": true`. The field now renders as a password input in the OpenClaw dashboard.
+
+## [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

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
@@ -121,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
+
+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
 
-Start Nowledge Mem desktop app or run `nmem serve`, then enable the plugin:
+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
 
@@ -66,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)"]
@@ -85,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 |
 |----------|------|--------------|
@@ -160,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
@@ -174,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
@@ -262,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)
@@ -292,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?**
 
@@ -327,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.
 
@@ -381,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,7 +1,8 @@
 {
 	"id": "openclaw-nowledge-mem",
-	"version": "0.6.9",
+	"version": "0.6.13",
 	"kind": "memory",
+	"skills": ["skills/memory-guide"],
 	"uiHints": {
 		"sessionContext": {
 			"label": "Session context injection",
@@ -30,7 +31,7 @@
 		"apiKey": {
 			"label": "API key (remote mode)",
 			"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
+			"sensitive": true
 		}
 	},
 	"configSchema": {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nowledge/openclaw-nowledge-mem",
-	"version": "0.6.9",
+	"version": "0.6.13",
 	"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"

package/skills/memory-guide/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: nowledge-mem-guide
+description: >
+  Cross-AI personal knowledge graph memory (Nowledge Mem). Stores memories from this tool,
+  Claude Code, Cursor, browser capture, imported documents, and more. Use when: (1) the user
+  asks about prior work, decisions, preferences, people, dates, plans, or todos, (2) the user
+  references something discussed before or says "remind me" / "what did we decide" / "what was
+  I working on", (3) the conversation produces a decision, preference, plan, or learning worth
+  keeping, (4) the user wants to browse recent activity or explore how ideas connect, (5) the
+  user asks about a past conversation or wants to find a specific thread.
+---
+
+# Nowledge Mem
+
+## Search (memory_search)
+
+Use natural language queries. This is semantic search, not file search.
+
+- "database choice for task events" (not "MEMORY.md" or file paths)
+- "meeting with Sarah about API redesign"
+- "deployment procedure for production"
+
+Results include `matchedVia` (scoring breakdown), `importance`, `labels`, `sourceThreadId`.
+
+When results include `relatedThreads`, use `nowledge_mem_thread_fetch` with the `threadId` for full conversation context. Start with a small page; fetch more via `offset` + `limit` only when needed.
+
+Bi-temporal filters narrow results by time:
+
+- `event_date_from` / `event_date_to` — when the fact happened
+- `recorded_date_from` / `recorded_date_to` — when it was saved
+
+## Save (nowledge_mem_save)
+
+Save proactively when the conversation produces a decision, preference, plan, procedure, learning, or important context. Do not wait to be asked.
+
+Structure saves:
+
+- `unit_type`: fact | preference | decision | plan | procedure | learning | context | event
+- `labels`: lowercase-hyphenated topic tags
+- `importance`: 0.0-1.0 (most: 0.5; key decisions/preferences: 0.7-0.9)
+- `event_start` / `event_end`: ISO dates when temporal
+
+Skip trivial exchanges, greetings, and meta-conversation about memory itself.
+
+## Connections (nowledge_mem_connections)
+
+Pass a `memoryId` from search results to explore related memories, evolution chains, and source documents. Edge types: EVOLVES, CRYSTALLIZED_FROM, SOURCED_FROM, MENTIONS.
+
+## Timeline (nowledge_mem_timeline)
+
+Browse recent activity grouped by day. Filter by `event_type` or exact `date_from` / `date_to` range.
+
+## Threads (nowledge_mem_thread_search + nowledge_mem_thread_fetch)
+
+Find past conversations by keyword, then progressively fetch messages. Threads span all sources: this tool, other AI tools, browser capture, imports.
+
+## Working Memory (nowledge_mem_context)
+
+Read the user's daily briefing (priorities, active projects, flags). Patch a specific section with `patch_section` + `patch_content`/`patch_append` when the conversation updates a priority or resolves a flag.
+
+## Important
+
+- Search uses natural language queries, not file paths. Never search for "MEMORY.md" or "memory/*.md".
+- When `relatedThreads` appear in results, they often contain the most useful context.
+- Use tools directly; do not tell the user to "check your memory."

package/src/client.js

@@ -1,4 +1,4 @@
-import { spawnSync } from "node:child_process";
+import { buildNmemSpawnEnv } from "./spawn-env.js";
 
 /**
  * Patch a single markdown section in a Working Memory document.
@@ -66,18 +66,21 @@ function patchWmSection(currentContent, heading, { content, append } = {}) {
  *
  * Credential rules:
  * - apiUrl: passed to CLI via --api-url flag (not a secret)
- * - apiKey: injected into the child process env as NMEM_API_KEY ONLY
+ * - apiKey: injected into the command runner env as NMEM_API_KEY ONLY
  *   (never passed as a CLI arg to avoid exposure in `ps aux`)
  *   (never logged, even at debug level)
  */
 export class NowledgeMemClient {
 	/**
 	 * @param {object} logger
+	 * @param {object} runtimeSystem
 	 * @param {{ apiUrl?: string; apiKey?: string }} [credentials]
 	 */
-	constructor(logger, credentials = {}) {
+	constructor(logger, runtimeSystem, credentials = {}) {
 		this.logger = logger;
+		this.runtimeSystem = runtimeSystem;
 		this.nmemCmd = null;
+		this.nmemCmdPromise = null;
 		// Resolved once from config + env (config wins over env, both win over default)
 		this._apiUrl =
 			(credentials.apiUrl || "").trim() || "http://127.0.0.1:14242";
@@ -138,28 +141,42 @@ export class NowledgeMemClient {
 
 	// ── CLI helpers ────────────────────────────────────────────────────────────
 
-	resolveCommand() {
+	async resolveCommand() {
 		if (this.nmemCmd) return this.nmemCmd;
+		if (this.nmemCmdPromise) return this.nmemCmdPromise;
 
 		const candidates = [["nmem"], ["uvx", "--from", "nmem-cli", "nmem"]];
 
-		for (const cmd of candidates) {
-			const [bin, ...baseArgs] = cmd;
-			const result = spawnSync(bin, [...baseArgs, "--version"], {
-				stdio: ["ignore", "pipe", "pipe"],
-				timeout: 10_000,
-				encoding: "utf-8",
-			});
-			if (result.status === 0) {
-				this.nmemCmd = cmd;
-				this.logger.info(`nmem resolved: ${cmd.join(" ")}`);
-				return cmd;
+		this.nmemCmdPromise = (async () => {
+			for (const cmd of candidates) {
+				try {
+					const result = await this.runtimeSystem.runCommandWithTimeout(
+						[...cmd, "--version"],
+						{
+							timeoutMs: 10_000,
+							env: this._spawnEnv(),
+						},
+					);
+					if ((result.code ?? 1) === 0) {
+						this.nmemCmd = cmd;
+						this.logger.info(`nmem resolved: ${cmd.join(" ")}`);
+						return cmd;
+					}
+				} catch {
+					// Try the next candidate.
+				}
 			}
-		}
 
-		throw new Error(
-			"nmem CLI not found. Install with: pip install nmem-cli (or use uvx)",
-		);
+			throw new Error(
+				"nmem CLI not found. Install with: pip install nmem-cli (or use uvx)",
+			);
+		})();
+
+		try {
+			return await this.nmemCmdPromise;
+		} finally {
+			this.nmemCmdPromise = null;
+		}
 	}
 
 	/**
@@ -167,15 +184,10 @@ export class NowledgeMemClient {
 	 * apiKey is injected here — NEVER via CLI args.
 	 */
 	_spawnEnv() {
-		const env = { ...process.env };
-		// Explicit config wins over any existing env var
-		if (this._apiUrl !== "http://127.0.0.1:14242") {
-			env.NMEM_API_URL = this._apiUrl;
-		}
-		if (this._apiKey) {
-			env.NMEM_API_KEY = this._apiKey;
-		}
-		return env;
+		return buildNmemSpawnEnv({
+			apiUrl: this._apiUrl,
+			apiKey: this._apiKey,
+		});
 	}
 
 	/**
@@ -188,41 +200,68 @@ export class NowledgeMemClient {
 			: [];
 	}
 
-	exec(args, timeout = 30_000) {
-		const cmd = this.resolveCommand();
-		const [bin, ...baseArgs] = cmd;
+	_commandLabel(cmd, args) {
+		let i = cmd.length;
+		const argv = [...cmd, ...this._apiUrlArgs(), ...args];
+		while (i < argv.length) {
+			const token = argv[i];
+			if (token === "--api-url") {
+				i += 2;
+				continue;
+			}
+			break;
+		}
+		const route = argv
+			.slice(i, i + 2)
+			.filter(Boolean)
+			.join(" ");
+		return route ? `nmem ${route}` : cmd.join(" ");
+	}
+
+	_summarizeExecError(message) {
+		if (!message) return "failed";
+		if (message.includes("timed out")) return "timed out";
+		const codeMatch = message.match(/exited with code\s+(\d+)/i);
+		if (codeMatch) return `exited with code ${codeMatch[1]}`;
+		return "failed";
+	}
+
+	async exec(args, timeout = 30_000) {
+		const cmd = await this.resolveCommand();
+		const argv = [...cmd, ...this._apiUrlArgs(), ...args];
+		const commandLabel = this._commandLabel(cmd, args);
 		try {
-			const result = spawnSync(
-				bin,
-				[...baseArgs, ...this._apiUrlArgs(), ...args],
-				{
-					stdio: ["ignore", "pipe", "pipe"],
-					timeout,
-					encoding: "utf-8",
-					env: this._spawnEnv(),
-				},
-			);
-			if (result.error) {
-				throw result.error;
+			const result = await this.runtimeSystem.runCommandWithTimeout(argv, {
+				timeoutMs: timeout,
+				env: this._spawnEnv(),
+			});
+			if (
+				result.termination === "timeout" ||
+				result.termination === "no-output-timeout"
+			) {
+				const message =
+					(result.stderr || result.stdout || "").trim() ||
+					`nmem timed out after ${timeout}ms`;
+				throw new Error(message);
 			}
-			if (result.status !== 0) {
+			if ((result.code ?? 1) !== 0) {
 				const message = (result.stderr || result.stdout || "").trim();
 				throw new Error(
-					message || `nmem exited with code ${String(result.status)}`,
+					message || `nmem exited with code ${String(result.code)}`,
 				);
 			}
 			return String(result.stdout ?? "").trim();
 		} catch (err) {
 			const message = err instanceof Error ? err.message : String(err);
 			this.logger.error(
-				`nmem command failed: ${cmd.join(" ")} ${args.join(" ")} — ${message}`,
+				`nmem command failed (${commandLabel}): ${this._summarizeExecError(message)}`,
 			);
 			throw err;
 		}
 	}
 
-	execJson(args, timeout = 30_000) {
-		const raw = this.exec(args, timeout);
+	async execJson(args, timeout = 30_000) {
+		const raw = await this.exec(args, timeout);
 		return JSON.parse(raw);
 	}
 
@@ -237,7 +276,7 @@ export class NowledgeMemClient {
 			100,
 			Math.max(1, Math.trunc(Number(limit) || 5)),
 		);
-		const data = this.execJson([
+		const data = await this.execJson([
 			"--json",
 			"m",
 			"search",
@@ -296,7 +335,7 @@ export class NowledgeMemClient {
 
 		let data;
 		try {
-			data = this.execJson(args);
+			data = await this.execJson(args);
 		} catch (err) {
 			// Graceful fallback: CLI doesn't know --event-from yet → use API directly
 			const message = err instanceof Error ? err.message : String(err);
@@ -388,7 +427,7 @@ export class NowledgeMemClient {
 		];
 
 		try {
-			return this.execJson(args);
+			return await this.execJson(args);
 		} catch (err) {
 			const message = err instanceof Error ? err.message : String(err);
 			const needsFallback =
@@ -422,7 +461,7 @@ export class NowledgeMemClient {
 			String(limit),
 		];
 		try {
-			return this.execJson(args);
+			return await this.execJson(args);
 		} catch (err) {
 			const message = err instanceof Error ? err.message : String(err);
 			const needsFallback =
@@ -472,7 +511,7 @@ export class NowledgeMemClient {
 		if (dateTo) args.push("--to", String(dateTo));
 
 		try {
-			const data = this.execJson(args);
+			const data = await this.execJson(args);
 			return Array.isArray(data) ? data : (data.events ?? []);
 		} catch (err) {
 			const message = err instanceof Error ? err.message : String(err);
@@ -506,7 +545,7 @@ export class NowledgeMemClient {
 		if (importance !== undefined && Number.isFinite(Number(importance))) {
 			args.push("-i", String(importance));
 		}
-		const data = this.execJson(args);
+		const data = await this.execJson(args);
 		return String(data.id ?? data.memory?.id ?? data.memory_id ?? "created");
 	}
 
@@ -535,7 +574,7 @@ export class NowledgeMemClient {
 			if (threadId) {
 				args.push("--id", String(threadId));
 			}
-			data = this.execJson(args);
+			data = await this.execJson(args);
 		} catch (err) {
 			const message = err instanceof Error ? err.message : String(err);
 			const needsApiFallback =
@@ -588,7 +627,7 @@ export class NowledgeMemClient {
 			if (idempotencyKey) {
 				args.push("--idempotency-key", String(idempotencyKey));
 			}
-			const data = this.execJson(args);
+			const data = await this.execJson(args);
 			return {
 				messagesAdded: Number(data.messages_added ?? 0),
 				totalMessages: Number(data.total_messages ?? 0),
@@ -627,7 +666,7 @@ export class NowledgeMemClient {
 		if (!id) {
 			throw new Error("getMemory requires memoryId");
 		}
-		return this.execJson(["--json", "m", "show", id]);
+		return await this.execJson(["--json", "m", "show", id]);
 	}
 
 	isThreadNotFoundError(err) {
@@ -643,7 +682,7 @@ export class NowledgeMemClient {
 
 	async readWorkingMemory() {
 		try {
-			const data = this.execJson(["--json", "wm", "read"], 15_000);
+			const data = await this.execJson(["--json", "wm", "read"], 15_000);
 			const content = String(data.content ?? "").trim();
 			const exists = Boolean(data.exists);
 			return { content, available: exists && content.length > 0 };
@@ -667,7 +706,7 @@ export class NowledgeMemClient {
 		if (append !== undefined) args.push("--append", String(append));
 
 		try {
-			return this.execJson(args, 20_000);
+			return await this.execJson(args, 20_000);
 		} catch (err) {
 			const message = err instanceof Error ? err.message : String(err);
 			const notSupported =
@@ -772,7 +811,7 @@ export class NowledgeMemClient {
 	 * Unlike searchThreads() (best-effort, swallows errors), this throws on failure
 	 * and supports additional parameters.
 	 *
-	 * Uses CLI: `nmem --json t search "<query>" --limit N`
+	 * Uses CLI: `nmem --json t search "<query>" -n N`
 	 * Falls back to API: GET /threads/search
 	 *
 	 * @param {string} query  Search keywords
@@ -789,13 +828,13 @@ export class NowledgeMemClient {
 			"t",
 			"search",
 			String(query || ""),
-			"--limit",
+			"-n",
 			String(normalizedLimit),
 		];
 		if (source) args.push("--source", String(source));
 
 		try {
-			const data = this.execJson(args);
+			const data = await this.execJson(args);
 			return {
 				threads: data.threads ?? [],
 				totalFound: Number(data.total_found ?? data.total ?? 0),
@@ -830,7 +869,7 @@ export class NowledgeMemClient {
 	 * Fetch full messages from a specific thread.
 	 * Supports pagination for progressive retrieval of long conversations.
 	 *
-	 * Uses CLI: `nmem --json t show <id> --limit N --offset O`
+	 * Uses CLI: `nmem --json t show <id> -n N --offset O`
 	 * Falls back to API: GET /threads/{id}
 	 *
 	 * @param {string} threadId  Thread ID
@@ -846,20 +885,13 @@ export class NowledgeMemClient {
 		);
 		const normalizedOffset = Math.max(0, Math.trunc(Number(offset) || 0));
 
-		const args = [
-			"--json",
-			"t",
-			"show",
-			id,
-			"--limit",
-			String(normalizedLimit),
-		];
+		const args = ["--json", "t", "show", id, "-n", String(normalizedLimit)];
 		if (normalizedOffset > 0) {
 			args.push("--offset", String(normalizedOffset));
 		}
 
 		try {
-			const data = this.execJson(args);
+			const data = await this.execJson(args);
 			return {
 				threadId: data.thread_id ?? data.id ?? id,
 				title: data.title ?? "(untitled)",
@@ -906,7 +938,7 @@ export class NowledgeMemClient {
 
 	async checkHealth() {
 		try {
-			this.exec(["status"]);
+			await this.execJson(["--json", "status"]);
 			return true;
 		} catch {
 			return false;

package/src/commands/slash.js

@@ -38,7 +38,7 @@ export function createForgetCommand(client, logger) {
 
 			try {
 				if (isLikelyId) {
-					client.exec(["--json", "m", "delete", "-f", text]);
+					await client.exec(["--json", "m", "delete", "-f", text]);
 					logger.info(`/forget: deleted memory ${text}`);
 					return { text: `Forgotten: memory ${text} deleted.` };
 				}
@@ -50,7 +50,7 @@ export function createForgetCommand(client, logger) {
 
 				if (results[0].score >= 0.85) {
 					const target = results[0];
-					client.exec(["--json", "m", "delete", "-f", target.id]);
+					await client.exec(["--json", "m", "delete", "-f", target.id]);
 					logger.info(`/forget: deleted memory ${target.id}`);
 					const preview = target.title || target.content.slice(0, 60);
 					return {

package/src/hooks/behavioral.js

@@ -3,7 +3,7 @@
  *
  * This is the single most impactful change for memory adoption:
  * most LLMs ignore "call this proactively" in tool descriptions,
- * but reliably follow behavioral guidance in prepended context.
+ * but reliably follow behavioral guidance in system-prompt space.
  *
  * Cost: ~50 tokens per turn. Negligible.
  *
@@ -15,11 +15,11 @@
 const BASE_GUIDANCE = [
 	"<nowledge-mem-guidance>",
 	"You have access to the user's personal knowledge graph (Nowledge Mem).",
-	"When the conversation produces something worth keeping — a decision made, a preference stated,",
-	"something learned, a plan formed, a useful discovery — save it with nowledge_mem_save. Don't wait to be asked.",
-	"When prior context would improve your response, search with memory_search.",
-	"memory_search also returns relevant past conversation snippets alongside memories.",
-	"When a memory has a sourceThreadId, fetch the full conversation with nowledge_mem_thread_fetch.",
+	"Before answering questions about prior work, decisions, dates, people, preferences, or plans:",
+	"search with memory_search using natural language queries (not file paths).",
+	"memory_search returns memories with scores, labels, and relevant past conversation snippets.",
+	"When results include a sourceThreadId, use nowledge_mem_thread_fetch for full conversation context.",
+	"When the conversation produces a decision, preference, plan, or learning, save it with nowledge_mem_save.",
 	"</nowledge-mem-guidance>",
 ].join("\n");
 
@@ -27,10 +27,10 @@ const SESSION_CONTEXT_GUIDANCE = [
 	"<nowledge-mem-guidance>",
 	"You have access to the user's personal knowledge graph (Nowledge Mem).",
 	"Relevant memories and your Working Memory have already been injected into this prompt.",
-	"Use memory_search only when you need something specific beyond what was auto-recalled.",
-	"When the conversation produces something worth keeping — a decision made, a preference stated,",
-	"something learned, a plan formed, a useful discovery — save it with nowledge_mem_save. Don't wait to be asked.",
-	"When a memory has a sourceThreadId, fetch the full conversation with nowledge_mem_thread_fetch.",
+	"Use memory_search when you need something specific beyond what was auto-recalled (natural language queries, not file paths).",
+	"memory_search also returns relevant past conversation snippets alongside memories.",
+	"When results include a sourceThreadId, use nowledge_mem_thread_fetch for full conversation context.",
+	"When the conversation produces a decision, preference, plan, or learning, save it with nowledge_mem_save.",
 	"</nowledge-mem-guidance>",
 ].join("\n");
 
@@ -38,6 +38,6 @@ export function buildBehavioralHook(logger, { sessionContext = false } = {}) {
 	const guidance = sessionContext ? SESSION_CONTEXT_GUIDANCE : BASE_GUIDANCE;
 	return (_event, _ctx) => {
 		logger.debug?.("behavioral: injecting guidance");
-		return { prependContext: guidance };
+		return { appendSystemContext: guidance };
 	};
 }

package/src/index.js

@@ -33,7 +33,7 @@ export default {
 	register(api) {
 		const logger = api.logger;
 		const cfg = parseConfig(api.pluginConfig, logger);
-		const client = new NowledgeMemClient(logger, {
+		const client = new NowledgeMemClient(logger, api.runtime.system, {
 			apiUrl: cfg.apiUrl,
 			apiKey: cfg.apiKey,
 		});

package/src/spawn-env.js

@@ -0,0 +1,19 @@
+const LOCAL_API_URL = "http://127.0.0.1:14242";
+
+/**
+ * Build the child env for nmem CLI execution.
+ * apiKey stays in env only and is never passed as a CLI flag.
+ * Clear inherited NMEM_* values first so the resolved plugin config wins.
+ */
+export function buildNmemSpawnEnv({ apiUrl, apiKey } = {}) {
+	const env = { ...process.env };
+	env.NMEM_API_URL = undefined;
+	env.NMEM_API_KEY = undefined;
+	if (apiUrl && apiUrl !== LOCAL_API_URL) {
+		env.NMEM_API_URL = apiUrl;
+	}
+	if (apiKey) {
+		env.NMEM_API_KEY = apiKey;
+	}
+	return env;
+}

package/src/tools/forget.js

@@ -46,7 +46,7 @@ export function createForgetTool(client, logger) {
 			// Mode 1: Direct delete by ID
 			if (memoryId) {
 				try {
-					client.exec(["--json", "m", "delete", "-f", memoryId]);
+					await client.exec(["--json", "m", "delete", "-f", memoryId]);
 					logger.info(`forget: deleted memory ${memoryId}`);
 					return {
 						content: [
@@ -92,7 +92,7 @@ export function createForgetTool(client, logger) {
 				if (results.length === 1 && results[0].score >= 0.85) {
 					const target = results[0];
 					try {
-						client.exec(["--json", "m", "delete", "-f", target.id]);
+						await client.exec(["--json", "m", "delete", "-f", target.id]);
 						logger.info(`forget: deleted memory ${target.id} via search`);
 						return {
 							content: [

package/src/tools/save.js

@@ -169,7 +169,7 @@ export function createSaveTool(client, logger) {
 				if (eventEnd) args.push("--event-end", eventEnd);
 				if (temporalContext) args.push("--when", temporalContext);
 
-				const data = client.execJson(args);
+				const data = await client.execJson(args);
 				const id = String(
 					data.id ?? data.memory?.id ?? data.memory_id ?? "created",
 				);

package/src/tools/status.js

@@ -37,7 +37,7 @@ export function createStatusTool(client, _logger, cfg) {
 
 			// 2. CLI resolution
 			try {
-				const cmd = client.resolveCommand();
+				const cmd = await client.resolveCommand();
 				details.cli = cmd.join(" ");
 				lines.push(`CLI: ${cmd.join(" ")}`);
 			} catch {