@nowledge/openclaw-nowledge-mem 0.6.8 → 0.6.12

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/config.js

@@ -19,6 +19,7 @@ const ALLOWED_KEYS = new Set([
 	"sessionDigest",
 	"digestMinInterval",
 	"maxContextResults",
+	"recallMinScore",
 	"apiUrl",
 	"apiKey",
 	// Legacy aliases — accepted but not advertised
@@ -135,7 +136,7 @@ function firstDefined(...options) {
  * will configure via OpenClaw's plugin settings UI (pluginConfig).
  *
  * Canonical keys: sessionContext, sessionDigest, digestMinInterval,
- *                 maxContextResults, apiUrl, apiKey
+ *                 maxContextResults, recallMinScore, apiUrl, apiKey
  *
  * Legacy aliases (accepted from all sources; never shown in docs):
  *   autoRecall → sessionContext
@@ -148,6 +149,7 @@ function firstDefined(...options) {
  *   NMEM_SESSION_DIGEST        — true/1/yes to enable (alias: NMEM_AUTO_CAPTURE)
  *   NMEM_DIGEST_MIN_INTERVAL   — seconds (0-86400)
  *   NMEM_MAX_CONTEXT_RESULTS   — integer (1-20)
+ *   NMEM_RECALL_MIN_SCORE      — integer (0-100)
  *   NMEM_API_URL               — remote server URL
  *   NMEM_API_KEY               — API key (never logged)
  */
@@ -234,6 +236,20 @@ export function parseConfig(raw, logger) {
 	const maxContextResults = Math.min(20, Math.max(1, Math.trunc(mcr.value)));
 	_sources.maxContextResults = mcr.source;
 
+	// --- recallMinScore: file > pluginConfig > env > default ---
+	const rmsEnv = envInt("NMEM_RECALL_MIN_SCORE");
+	const rms = firstDefined(
+		{ value: pickNum(resolvedFile, "recallMinScore"), source: "file" },
+		{
+			value: pickNum(resolvedPlugin, "recallMinScore"),
+			source: "pluginConfig",
+		},
+		{ value: rmsEnv, source: "env" },
+		{ value: 0, source: "default" },
+	);
+	const recallMinScore = Math.min(100, Math.max(0, Math.trunc(rms.value)));
+	_sources.recallMinScore = rms.source;
+
 	// --- apiUrl: file > pluginConfig > env > "" ---
 	const fileUrl =
 		typeof resolvedFile.apiUrl === "string" && resolvedFile.apiUrl.trim();
@@ -267,6 +283,7 @@ export function parseConfig(raw, logger) {
 		sessionDigest,
 		digestMinInterval,
 		maxContextResults,
+		recallMinScore,
 		apiUrl,
 		apiKey,
 		_sources,

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/hooks/capture.js

@@ -250,7 +250,10 @@ function buildConversationText(normalized) {
 	const parts = [];
 	let total = 0;
 	for (const m of normalized) {
-		const text = truncate(m.fullContent || m.content, MAX_DISTILL_MESSAGE_CHARS);
+		const text = truncate(
+			m.fullContent || m.content,
+			MAX_DISTILL_MESSAGE_CHARS,
+		);
 		const line = `${m.role}: ${text}`;
 		if (total + line.length > MAX_CONVERSATION_CHARS) break;
 		parts.push(line);
@@ -297,7 +300,9 @@ export function buildAgentEndCaptureHandler(client, cfg, logger) {
 
 		//    Skip when no new messages were added (e.g. heartbeat re-sync).
 		if (!result || result.messagesAdded === 0) {
-			logger.debug?.("capture: no new messages since last sync, skipping triage");
+			logger.debug?.(
+				"capture: no new messages since last sync, skipping triage",
+			);
 			return;
 		}