@nowledge/openclaw-nowledge-mem 0.8.27 → 0.8.31

package/CHANGELOG.md

@@ -4,6 +4,32 @@ All notable changes to the Nowledge Mem OpenClaw plugin will be documented in th
 
 ## Unreleased
 
+## [0.8.31] - 2026-07-12
+
+### Improved
+
+- New OpenClaw Threads use the first meaningful user message as their title instead of exposing an internal `agent:...` session key. When no user turn is available, the plugin falls back to a readable channel label such as `OpenClaw · WeChat`.
+
+## [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

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`:
 
@@ -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.
 

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,8 @@ 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,7 +2,7 @@
 	"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.27",
+	"version": "0.8.31",
 	"kind": ["memory", "context-engine"],
 	"contracts": {
 		"tools": [

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@nowledge/openclaw-nowledge-mem",
 	"displayName": "Nowledge Mem for OpenClaw",
-	"version": "0.8.27",
+	"version": "0.8.31",
 	"type": "module",
 	"description": "Nowledge Mem memory plugin for OpenClaw, local-first personal knowledge base",
 	"author": {

package/src/hooks/capture.js

@@ -12,6 +12,7 @@ export const DEFAULT_MAX_MESSAGE_CHARS = 800;
 export const MAX_DISTILL_MESSAGE_CHARS = 2000;
 export const MAX_CONVERSATION_CHARS = 30_000;
 export const MIN_MESSAGES_FOR_DISTILL = 4;
+export const MAX_THREAD_TITLE_CHARS = 80;
 const SESSION_RESET_PROMPT_PREFIX =
 	"A new session was started via /new or /reset.";
 const OPENCLAW_DIRECTIVE_TAG_RE =
@@ -246,8 +247,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 =
@@ -302,9 +310,47 @@ export function normalizeRoleMessage(
 	};
 }
 
-export function buildThreadTitle(ctx) {
-	const session = ctx?.sessionKey || ctx?.sessionId || "session";
-	return `OpenClaw ${session}`;
+function humanizeChannel(value) {
+	const normalized = String(value || "")
+		.trim()
+		.toLowerCase();
+	if (!normalized) return "";
+	const known = {
+		dashboard: "Dashboard",
+		"openclaw-weixin": "WeChat",
+		weixin: "WeChat",
+		wechat: "WeChat",
+		telegram: "Telegram",
+		discord: "Discord",
+		whatsapp: "WhatsApp",
+	};
+	if (known[normalized]) return known[normalized];
+	return normalized
+		.replace(/^openclaw[-_]/, "")
+		.split(/[-_]+/)
+		.filter(Boolean)
+		.map((part) => `${part.charAt(0).toUpperCase()}${part.slice(1)}`)
+		.join(" ");
+}
+
+export function buildThreadTitle(ctx, normalizedMessages = []) {
+	const firstUserMessage = normalizedMessages.find(
+		(message) => message?.role === "user",
+	);
+	const userText = String(
+		firstUserMessage?.fullContent || firstUserMessage?.content || "",
+	)
+		.replace(/\s+/gu, " ")
+		.trim();
+	if (userText) return truncate(userText, MAX_THREAD_TITLE_CHARS);
+
+	const explicitChannel = ctx?.channel || ctx?.channelId;
+	const sessionKey = String(ctx?.sessionKey || "");
+	const sessionParts = sessionKey.split(":").filter(Boolean);
+	const sessionChannel =
+		sessionParts[0]?.toLowerCase() === "agent" ? sessionParts[2] : "";
+	const channel = humanizeChannel(explicitChannel || sessionChannel);
+	return channel ? `OpenClaw · ${channel}` : "OpenClaw conversation";
 }
 
 function sanitizeIdPart(input, max = 48) {
@@ -416,11 +462,11 @@ export async function appendOrCreateThread({
 	const threadId = buildStableThreadId(event, ctx);
 	const sessionKey = String(ctx?.sessionKey || ctx?.sessionId || "session");
 	const sessionId = String(ctx?.sessionId || "").trim();
-	const title = buildThreadTitle(ctx);
 	const normalized = rawMessages
 		.map((message) => normalizeRoleMessage(message, maxMessageChars))
 		.filter(Boolean);
 	if (normalized.length === 0) return;
+	const title = buildThreadTitle(ctx, normalized);
 
 	const buildMessages = (resolvedMessageMode) =>
 		normalized.map((message, index) => ({
@@ -662,7 +708,7 @@ export async function triageAndDistill({
 
 		const distillResult = await client.distillThread({
 			threadId: captureResult.threadId,
-			title: buildThreadTitle(ctx),
+			title: buildThreadTitle(ctx, captureResult.normalized),
 			content: conversationText,
 		});
 

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) {