@nowledge/openclaw-nowledge-mem 0.8.26 → 0.8.30

package/CHANGELOG.md

@@ -4,6 +4,33 @@ All notable changes to the Nowledge Mem OpenClaw plugin will be documented in th
 
 ## Unreleased
 
+## [0.8.30] - 2026-07-12
+
+### Fixed
+
+- Setup guidance now preserves existing OpenClaw tool policy while granting the complete plugin contract under restrictive profiles such as `coding`. It uses the plugin id in `tools.alsoAllow` (or an existing `tools.allow`) instead of fragile individual tool names.
+- Setup now explicitly grants `plugins.entries.openclaw-nowledge-mem.hooks.allowConversationAccess=true`, which current OpenClaw releases require before non-bundled plugins can use `agent_end` as the thread-capture safety net.
+- `nowledge_mem_status` now reports restricted tool profiles and blocked conversation hooks instead of claiming all tools and both capture paths are active.
+
+## [0.8.29] - 2026-07-11
+
+### Fixed
+
+- Conversation capture now converts OpenClaw's numeric message timestamps to the textual timestamp format required by Mem. Automatic thread sync no longer stops while memory tools continue to work.
+
+## [0.8.28] - 2026-07-08
+
+### Improved
+
+- `nowledge_mem_status` now checks OpenClaw's Mem HTTP thread-sync API separately from the `nmem` CLI. This makes session-capture issues visible when memory tools still work but conversation sync cannot reach `/threads`.
+
+## [0.8.27] - 2026-06-26
+
+### Fixed
+
+- OpenClaw 2026.6.10+ now loads the plugin correctly. The plugin manifest declares all Nowledge Mem agent tools through `contracts.tools`, matching OpenClaw's newer tool-ownership contract and preventing startup failures such as `must declare contracts.tools before registering agent tools`.
+- Thread sync, memory search, and `nowledge_mem_status` are available again after upgrading OpenClaw and restarting the gateway.
+
 ## [0.8.26] - 2026-06-10
 
 ### Fixed

package/README.md

@@ -17,7 +17,15 @@ This is not a flat note store. Nowledge Mem links related knowledge into a graph
 openclaw plugins install clawhub:@nowledge/openclaw-nowledge-mem
 ```
 
-OpenClaw's installer writes the install record, enables the plugin, and switches the `memory` slot to `openclaw-nowledge-mem`. On current OpenClaw builds, that same install flow may also set `plugins.slots.contextEngine` to `openclaw-nowledge-mem`. Plugin `0.8.18+` accepts that automatically as a compatibility alias, so you do not need to hand-edit the file after install. If you manage config manually, keep using the canonical context engine id `nowledge-mem`.
+OpenClaw's installer writes the install record, enables the plugin, and switches the `memory` slot to `openclaw-nowledge-mem`. On current OpenClaw builds, that same install flow may also set `plugins.slots.contextEngine` to `openclaw-nowledge-mem`. Plugin `0.8.18+` accepts that automatically as a compatibility alias.
+
+Grant the conversation hook used as the thread-sync safety net:
+
+```bash
+openclaw config set plugins.entries.openclaw-nowledge-mem.hooks.allowConversationAccess true --strict-json
+```
+
+If `openclaw config get tools` shows a restrictive profile such as `coding`, preserve its existing policy and add `openclaw-nowledge-mem` to `tools.alsoAllow`. If `tools.allow` already exists, add the plugin id there instead. The plugin id expands to all manifest-declared tools; do not list individual `nowledge_mem_*` names.
 
 To update the plugin, re-run the ClawHub install with `--force`:
 
@@ -135,7 +143,7 @@ NMEM_SPACE="Research Agent"
 
 Nowledge Mem's CLI-backed Working Memory, memory search/save, and the plugin's API-backed thread/feed fallbacks will then stay in that lane together. There is no second OpenClaw-only vault setting; the shared Mem boundary is still one hidden space key, but humans and agents should normally work with the space name instead.
 
-For multi-agent orchestrators, set `NMEM_AGENT_ID=<agent-slug>` per spawned OpenClaw worker. Add `NMEM_SPACE` only when that run should override the AI Identity's default space. `NMEM_HOST_AGENT_ID` is for advanced host-id aliases. Context Bundle will use the stable identity while keeping `source_app=openclaw` for provenance. Keep these as launcher environment variables instead of plugin config keys so OpenClaw's strict config validation remains stable.
+For multi-agent orchestrators, set `NMEM_AGENT_ID=<agent-slug>` per spawned OpenClaw worker. Add `NMEM_SPACE` only when that run should override the AI Identity's default space. `NMEM_HOST_AGENT_ID` is for advanced external aliases. Context Bundle will use the stable identity while keeping `source_app=openclaw` for provenance. Keep these as launcher environment variables instead of plugin config keys so OpenClaw's strict config validation remains stable.
 
 Shared spaces, default retrieval, and agent guidance still live in Mem's own space profile. OpenClaw chooses the lane and preserves it across transports; it should not duplicate the profile semantics.
 
@@ -434,7 +442,7 @@ openclaw nowledge-mem status
 
 ## Configuration
 
-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.
+The plugin defaults work for local Mem, and `openclaw plugins install` enables the plugin and selects the memory slot. Current OpenClaw releases still require one explicit conversation-hook grant for the `agent_end` capture fallback. Restrictive tool profiles also need the plugin id added to their effective allow policy; see Installation above.
 
 To change settings, use the OpenClaw plugin settings UI. Changes take effect on restart.
 
@@ -556,6 +564,8 @@ All 10 plugin tools register automatically when the plugin loads. No tool-level
 }
 ```
 
+If OpenClaw logs `must declare contracts.tools before registering agent tools`, update the plugin to `0.8.27` or newer and restart OpenClaw. That error means a newer OpenClaw build is enforcing plugin tool ownership metadata before it accepts runtime tool registration.
+
 **`corpusSupplement: true` is set, but startup still logs `corpus=false`**
 
 Update to `0.8.15` or newer. Older builds could disable the plugin too early when `memory-core` owned the memory slot, which made supplement mode look unavailable even on new OpenClaw builds.

package/SKILL.md

@@ -129,6 +129,37 @@ Important facts:
 
 Do not tell the user to hand-edit those settings unless they are using a manual/path setup.
 
+### Step 3a — Grant the Runtime Capabilities the Plugin Uses
+
+Current OpenClaw releases require an explicit grant before a non-bundled plugin
+can read conversation content from `agent_end`. Set it after install:
+
+```bash
+openclaw config set plugins.entries.openclaw-nowledge-mem.hooks.allowConversationAccess true --strict-json
+```
+
+Then inspect the host's effective tool policy:
+
+```bash
+openclaw config get tools
+```
+
+- If `tools.allow` already exists, preserve that list and add
+  `openclaw-nowledge-mem` to it.
+- Otherwise, when a restrictive profile such as `coding`, `messaging`, or
+  `minimal` is set, preserve `tools.alsoAllow` and add
+  `openclaw-nowledge-mem` to it.
+- If no restrictive profile or allowlist exists, no tool-policy change is
+  needed.
+- Never replace an existing list, and never add individual `nowledge_mem_*`
+  names. The plugin id expands to the complete manifest-declared tool contract.
+
+Example for a `coding` profile with no prior `alsoAllow` entries:
+
+```bash
+openclaw config set tools.alsoAllow '["openclaw-nowledge-mem"]' --strict-json
+```
+
 ### Step 4 — Configure Remote Only When Needed
 
 Local mode:
@@ -189,7 +220,7 @@ First check the plugin status:
 openclaw nowledge-mem status
 ```
 
-If only `memory_search` and `memory_get` tools are available (other Nowledge Mem tools missing), the memory slot may still point to the built-in `memory-core`. Verify the slot in `~/.openclaw/openclaw.json`:
+If only `memory_search` and `memory_get` tools are available (other Nowledge Mem tools missing), inspect `openclaw config get tools` first. A restrictive profile needs the plugin id in `tools.alsoAllow`, or in the existing `tools.allow` list. Then verify the memory slot in `~/.openclaw/openclaw.json`:
 
 ```json
 {
@@ -253,7 +284,9 @@ What to expect:
 | `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` |
-| Plugin tools missing | Ensure the plugin is in `plugins.allow: ["openclaw-nowledge-mem"]`. Do **not** put `nowledge_mem_*` tool names in `tools.allow` — OpenClaw silently strips plugin-only allowlists. No `tools.*` config is needed; plugin tools load automatically when the plugin is allowed. |
+| Plugin tools missing | Inspect `openclaw config get tools`. Under a restrictive profile, preserve `tools.alsoAllow` and add `openclaw-nowledge-mem`; if `tools.allow` already exists, add the plugin id there instead. Do not add individual `nowledge_mem_*` names. Also ensure the plugin is trusted in `plugins.allow`. |
+| Memory tools work but Threads do not sync | Update to `0.8.30+`, set `plugins.entries.openclaw-nowledge-mem.hooks.allowConversationAccess=true`, restart the gateway, and verify with `nmem t list --source openclaw -n 20`. |
+| `must declare contracts.tools before registering agent tools` | Update the plugin to `0.8.27+` and restart OpenClaw. Newer OpenClaw builds require plugin authors to declare tool ownership in the manifest before runtime tool registration. |
 
 ## Notes for Agents
 

package/openclaw.plugin.json

@@ -2,8 +2,22 @@
 	"id": "openclaw-nowledge-mem",
 	"name": "Nowledge Mem",
 	"description": "Cross-tool knowledge graph memory for OpenClaw with startup context, graph search, and session distillation.",
-	"version": "0.8.26",
+	"version": "0.8.30",
 	"kind": ["memory", "context-engine"],
+	"contracts": {
+		"tools": [
+			"memory_search",
+			"memory_get",
+			"nowledge_mem_save",
+			"nowledge_mem_context",
+			"nowledge_mem_connections",
+			"nowledge_mem_timeline",
+			"nowledge_mem_forget",
+			"nowledge_mem_thread_search",
+			"nowledge_mem_thread_fetch",
+			"nowledge_mem_status"
+		]
+	},
 	"skills": [
 		"skills/memory-guide"
 	],

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@nowledge/openclaw-nowledge-mem",
 	"displayName": "Nowledge Mem for OpenClaw",
-	"version": "0.8.26",
+	"version": "0.8.30",
 	"type": "module",
 	"description": "Nowledge Mem memory plugin for OpenClaw, local-first personal knowledge base",
 	"author": {
@@ -29,13 +29,15 @@
 			"./src/index.js"
 		],
 		"install": {
-			"npmSpec": "@nowledge/openclaw-nowledge-mem"
+			"clawhubSpec": "clawhub:@nowledge/openclaw-nowledge-mem",
+			"npmSpec": "@nowledge/openclaw-nowledge-mem",
+			"defaultChoice": "clawhub"
 		},
 		"compat": {
 			"pluginApi": ">=2026.5.3"
 		},
 		"build": {
-			"openclawVersion": "2026.5.3"
+			"openclawVersion": "2026.6.10"
 		},
 		"release": {
 			"publishToClawHub": true,

package/src/hooks/capture.js

@@ -246,8 +246,15 @@ export function normalizeRoleMessage(
 	if (role === "user" && text.startsWith("/")) return null;
 
 	let timestamp;
-	if (typeof msg.timestamp === "string" || typeof msg.timestamp === "number") {
+	if (typeof msg.timestamp === "string") {
 		timestamp = msg.timestamp;
+	} else if (
+		typeof msg.timestamp === "number" &&
+		Number.isFinite(msg.timestamp)
+	) {
+		// OpenClaw emits epoch milliseconds, while Mem's thread API deliberately
+		// accepts textual timestamps so every connector shares one wire contract.
+		timestamp = new Date(msg.timestamp).toISOString();
 	}
 
 	const openclawMeta =

package/src/index.js

@@ -78,6 +78,12 @@ export default {
 		//   - memory/context-engine slot routing for capture and recall
 		const contextEngineSlot = api.config?.plugins?.slots?.contextEngine;
 		const pluginsAllow = api.config?.plugins?.allow;
+		const pluginEntry = api.config?.plugins?.entries?.[api.id];
+		const toolsProfile = api.config?.tools?.profile;
+		const toolsAllow = api.config?.tools?.allow;
+		const toolsAlsoAllow = api.config?.tools?.alsoAllow;
+		const allowConversationAccess =
+			pluginEntry?.hooks?.allowConversationAccess === true;
 		let contextEngineRegistered = false;
 		let contextEngineRegistrationError = null;
 		let corpusSupplementActive = false;
@@ -140,6 +146,10 @@ export default {
 				contextEngineSlot,
 				contextEngineIds: NOWLEDGE_MEM_CONTEXT_ENGINE_IDS,
 				pluginsAllow,
+				toolsProfile,
+				toolsAllow,
+				toolsAlsoAllow,
+				allowConversationAccess,
 				contextEngineRegistered,
 				contextEngineRegistrationError,
 				corpusSupplementActive,

package/src/tools/status.js

@@ -27,10 +27,10 @@ export function createStatusTool(client, _logger, cfg, runtimeInfo = {}) {
 			const lines = [];
 			const details = {};
 			const sources = cfg._sources || {};
+			const pluginId = "openclaw-nowledge-mem";
 
 			// 0a. Plugin trust check — detect missing plugins.allow
 			const pluginsAllow = runtimeInfo.pluginsAllow;
-			const pluginId = "openclaw-nowledge-mem";
 			details.pluginsAllow = !Array.isArray(pluginsAllow)
 				? "(not set)"
 				: pluginsAllow.includes(pluginId)
@@ -64,7 +64,48 @@ export function createStatusTool(client, _logger, cfg, runtimeInfo = {}) {
 				lines.push(`Plugin trust: ${pluginId} (allowlisted)`);
 			}
 
-			// 0b. Memory slot check — show current mode and options
+			// 0b. Effective tool policy. OpenClaw profiles are restrictive; the
+			// plugin id expands to this plugin's declared tool contract.
+			const toolsProfile = runtimeInfo.toolsProfile;
+			const toolsAllow = Array.isArray(runtimeInfo.toolsAllow)
+				? runtimeInfo.toolsAllow
+				: null;
+			const toolsAlsoAllow = Array.isArray(runtimeInfo.toolsAlsoAllow)
+				? runtimeInfo.toolsAlsoAllow
+				: null;
+			const profileRestrictsPlugins =
+				typeof toolsProfile === "string" && toolsProfile !== "full";
+			const pluginExplicitlyAllowed =
+				toolsAllow?.includes(pluginId) || toolsAlsoAllow?.includes(pluginId);
+			const toolPolicyBlocksPlugin =
+				(toolsAllow !== null && !toolsAllow.includes(pluginId)) ||
+				(profileRestrictsPlugins && !pluginExplicitlyAllowed);
+			details.toolsProfile = toolsProfile ?? "(not set)";
+			details.pluginToolsAllowed = !toolPolicyBlocksPlugin;
+			if (toolPolicyBlocksPlugin) {
+				lines.push(
+					`⚠ Tool policy does not expose the complete ${pluginId} tool contract.`,
+				);
+				if (toolsAllow !== null) {
+					lines.push(
+						`  Fix: preserve tools.allow and add "${pluginId}" to that list.`,
+					);
+				} else {
+					lines.push(
+						`  Fix: preserve tools.alsoAllow and add "${pluginId}" to that list.`,
+					);
+				}
+				lines.push(
+					"  Do not list individual nowledge_mem_* tools; use the plugin id so the manifest contract stays complete.",
+				);
+				lines.push("");
+			} else if (toolsProfile) {
+				lines.push(
+					`Tool policy: ${toolsProfile} profile + ${pluginId} (complete contract allowed)`,
+				);
+			}
+
+			// 0c. Memory slot check — show current mode and options
 			const memorySlot = runtimeInfo.memorySlot;
 			const contextEngineSlot = runtimeInfo.contextEngineSlot;
 			const contextEngineRegistered =
@@ -135,14 +176,20 @@ export function createStatusTool(client, _logger, cfg, runtimeInfo = {}) {
 				lines.push("Memory slot: openclaw-nowledge-mem (active)");
 			}
 
-			// 0c. Capture routing — hooks vs context engine
+			// 0d. Capture routing — hooks vs context engine
 			const ceActive =
 				isNowledgeMemContextEngineSlot(ceSlot) && contextEngineRegistered;
+			const hookCaptureAllowed = runtimeInfo.allowConversationAccess === true;
+			details.allowConversationAccess = hookCaptureAllowed;
 			const captureMode = !cfg.sessionDigest
 				? "disabled"
 				: ceActive
-					? "context-engine+hooks"
-					: "hooks";
+					? hookCaptureAllowed
+						? "context-engine+hooks"
+						: "context-engine"
+					: hookCaptureAllowed
+						? "hooks"
+						: "blocked";
 			details.captureMode = captureMode;
 			if (ceActive) {
 				if (ceSlot === NOWLEDGE_MEM_CONTEXT_ENGINE_COMPAT_ALIAS) {
@@ -158,7 +205,9 @@ export function createStatusTool(client, _logger, cfg, runtimeInfo = {}) {
 					);
 				}
 				lines.push(
-					"  Thread capture runs through Context Engine afterTurn with hook fallback (agent_end, after_compaction, before_reset).",
+					hookCaptureAllowed
+						? "  Thread capture runs through Context Engine afterTurn with hook fallback (agent_end, after_compaction, before_reset)."
+						: "  Thread capture runs through Context Engine afterTurn; the agent_end fallback is blocked by OpenClaw policy.",
 				);
 			} else if (isNowledgeMemContextEngineSlot(ceSlot)) {
 				if (ceSlot === NOWLEDGE_MEM_CONTEXT_ENGINE_COMPAT_ALIAS) {
@@ -194,6 +243,14 @@ export function createStatusTool(client, _logger, cfg, runtimeInfo = {}) {
 			if (!cfg.sessionDigest) {
 				lines.push("Thread capture: disabled (sessionDigest=false)");
 			} else {
+				if (!hookCaptureAllowed) {
+					lines.push(
+						"⚠ Hook fallback blocked: set plugins.entries.openclaw-nowledge-mem.hooks.allowConversationAccess=true.",
+					);
+					lines.push(
+						"  OpenClaw requires this explicit grant before a non-bundled plugin can read agent_end conversation content.",
+					);
+				}
 				lines.push(
 					"  Thread identity follows OpenClaw session lifecycle: /new or /reset starts a fresh thread, while compaction stays in the same thread.",
 				);
@@ -228,38 +285,68 @@ export function createStatusTool(client, _logger, cfg, runtimeInfo = {}) {
 				lines.push("CLI: not found (install with: pip install nmem-cli)");
 			}
 
-			// 3. Backend health
-			let healthy = false;
+			// 3. Backend health. Memory tools and thread capture travel through
+			// different surfaces: most reads/writes use the nmem CLI, while thread
+			// auto-sync writes directly to the HTTP API so large transcripts do not
+			// become argv-sized blobs. Report them separately; otherwise `nmem status`
+			// can produce a false green for users whose conversation capture is broken.
+			let cliHealthy = false;
 			try {
-				healthy = await client.checkHealth();
+				cliHealthy = await client.checkHealth();
 			} catch {
 				// checkHealth already returns false on error
 			}
-			details.healthy = healthy;
+			details.cliBackendReachable = cliHealthy;
 
-			if (healthy) {
-				lines.push("Backend: reachable");
-				// Fetch detailed health info
-				try {
-					const health = await client.apiJson(
-						"GET",
-						"/health",
-						undefined,
-						5000,
+			lines.push(`CLI backend: ${cliHealthy ? "reachable" : "not reachable"}`);
+
+			let httpHealthy = false;
+			try {
+				const health = await client.apiJson("GET", "/health", undefined, 5000);
+				httpHealthy = true;
+				if (health.version) {
+					details.version = health.version;
+					lines.push(`Version: ${health.version}`);
+				}
+				if (health.database_connected !== undefined) {
+					details.databaseConnected = health.database_connected;
+					lines.push(
+						`Database: ${health.database_connected ? "connected" : "disconnected"}`,
 					);
-					if (health.version) {
-						details.version = health.version;
-						lines.push(`Version: ${health.version}`);
-					}
-					if (health.database_connected !== undefined) {
-						details.databaseConnected = health.database_connected;
-						lines.push(
-							`Database: ${health.database_connected ? "connected" : "disconnected"}`,
-						);
-					}
-				} catch {
-					// Health endpoint not available on older backends
 				}
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err);
+				details.httpHealthError = message;
+			}
+			details.httpBackendReachable = httpHealthy;
+
+			let threadApiHealthy = false;
+			try {
+				await client.apiJson("GET", "/threads/sources", undefined, 5000);
+				threadApiHealthy = true;
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err);
+				details.threadSyncHttpError = message;
+			}
+			details.threadSyncHttpReachable = threadApiHealthy;
+			details.healthy = cliHealthy && threadApiHealthy;
+
+			if (threadApiHealthy) {
+				lines.push("Thread sync HTTP API: reachable");
+			} else {
+				lines.push("Thread sync HTTP API: not reachable");
+				lines.push(
+					"  Conversation capture writes to the Mem HTTP API. It will not sync while this is unreachable, even if memory tools still work through the CLI.",
+				);
+				if (details.threadSyncHttpError) {
+					lines.push(`  Detail: ${details.threadSyncHttpError}`);
+				}
+			}
+
+			if (cliHealthy && threadApiHealthy) {
+				lines.push("Backend: reachable");
+			} else if (cliHealthy || threadApiHealthy || httpHealthy) {
+				lines.push("Backend: partially reachable");
 			} else {
 				lines.push("Backend: not reachable");
 				if (remote) {