@nowledge/openclaw-nowledge-mem 0.6.5 → 0.6.8

package/src/config.js

@@ -1,3 +1,7 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
 export const API_DEFAULT_URL = "http://127.0.0.1:14242";
 
 /**
@@ -17,6 +21,11 @@ const ALLOWED_KEYS = new Set([
 	"maxContextResults",
 	"apiUrl",
 	"apiKey",
+	// Legacy aliases — accepted but not advertised
+	"autoRecall",
+	"autoCapture",
+	"captureMinInterval",
+	"maxRecallResults",
 ]);
 
 // Backward-compatible aliases (old names → new names).
@@ -28,11 +37,69 @@ const ALIAS_KEYS = {
 	maxRecallResults: "maxContextResults",
 };
 
-export function parseConfig(raw) {
-	const obj = raw && typeof raw === "object" ? raw : {};
+// --- config file ---------------------------------------------------------
+
+const CONFIG_DIR = join(homedir(), ".nowledge-mem");
+const CONFIG_PATH = join(CONFIG_DIR, "openclaw.json");
+
+/**
+ * Read ~/.nowledge-mem/openclaw.json if it exists.
+ * Returns {} when the file is missing or unreadable.
+ */
+function readConfigFile(logger) {
+	try {
+		if (!existsSync(CONFIG_PATH)) {
+			return {};
+		}
+		const content = readFileSync(CONFIG_PATH, "utf-8").trim();
+		if (!content) return {};
+		return JSON.parse(content);
+	} catch (err) {
+		logger?.warn?.(
+			`nowledge-mem: could not read ${CONFIG_PATH}: ${err instanceof Error ? err.message : err}`,
+		);
+		return {};
+	}
+}
+
+/** Exported for tests / CLI tooling. */
+export { CONFIG_PATH };
+
+// --- env var helpers -----------------------------------------------------
+
+function envStr(name) {
+	const v = process.env[name];
+	return typeof v === "string" ? v.trim() : undefined;
+}
+
+function envBool(name, fallbackName) {
+	const v = envStr(name) ?? envStr(fallbackName);
+	if (v === undefined) return undefined;
+	return v === "true" || v === "1" || v === "yes";
+}
+
+function envInt(name) {
+	const v = envStr(name);
+	if (v === undefined) return undefined;
+	const n = Number.parseInt(v, 10);
+	return Number.isFinite(n) ? n : undefined;
+}
+
+// --- helpers to read a boolean/number from resolved sources --------------
+
+function pickBool(obj, key) {
+	if (typeof obj[key] === "boolean") return obj[key];
+	return undefined;
+}
+
+function pickNum(obj, key) {
+	if (typeof obj[key] === "number" && Number.isFinite(obj[key]))
+		return obj[key];
+	return undefined;
+}
 
-	// Resolve aliases: copy old-name values to new-name slots
-	// (new name takes precedence if both are present).
+/** Resolve legacy aliases in an object: old names → new names. */
+function resolveAliases(obj) {
 	const resolved = { ...obj };
 	for (const [oldKey, newKey] of Object.entries(ALIAS_KEYS)) {
 		if (oldKey in resolved) {
@@ -42,50 +109,166 @@ export function parseConfig(raw) {
 			delete resolved[oldKey];
 		}
 	}
+	return resolved;
+}
+
+/**
+ * Return the first option whose value is not undefined.
+ * Each option is { value, source } where source is a label like
+ * "file", "pluginConfig", "env", or "default".
+ */
+function firstDefined(...options) {
+	for (const opt of options) {
+		if (opt.value !== undefined) return opt;
+	}
+	return options[options.length - 1];
+}
+
+// -------------------------------------------------------------------------
 
-	// Strict: reject unknown keys so users catch typos immediately.
-	const unknownKeys = Object.keys(resolved).filter((k) => !ALLOWED_KEYS.has(k));
+/**
+ * Parse plugin config with cascade:
+ *   ~/.nowledge-mem/openclaw.json > pluginConfig > env vars > defaults
+ *
+ * The config file (if it exists) takes highest priority so users who
+ * create it get predictable behavior. Most users won't have one and
+ * will configure via OpenClaw's plugin settings UI (pluginConfig).
+ *
+ * Canonical keys: sessionContext, sessionDigest, digestMinInterval,
+ *                 maxContextResults, apiUrl, apiKey
+ *
+ * Legacy aliases (accepted from all sources; never shown in docs):
+ *   autoRecall → sessionContext
+ *   autoCapture → sessionDigest
+ *   captureMinInterval → digestMinInterval
+ *   maxRecallResults → maxContextResults
+ *
+ * Environment variables (all optional):
+ *   NMEM_SESSION_CONTEXT       — true/1/yes to enable (alias: NMEM_AUTO_RECALL)
+ *   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_API_URL               — remote server URL
+ *   NMEM_API_KEY               — API key (never logged)
+ */
+export function parseConfig(raw, logger) {
+	const pluginCfg = raw && typeof raw === "object" ? raw : {};
+	const fileCfg = readConfigFile(logger);
+
+	// Resolve aliases in both sources
+	const resolvedPlugin = resolveAliases(pluginCfg);
+	const resolvedFile = resolveAliases(fileCfg);
+
+	// Strict: reject unknown keys in pluginConfig (typo catcher).
+	const unknownKeys = Object.keys(resolvedPlugin).filter(
+		(k) => !ALLOWED_KEYS.has(k),
+	);
 	if (unknownKeys.length > 0) {
 		throw new Error(
 			`nowledge-mem: unknown config key${unknownKeys.length > 1 ? "s" : ""}: ${unknownKeys.join(", ")}. ` +
-				`Allowed keys: ${[...ALLOWED_KEYS].join(", ")}`,
+				`Allowed keys: ${[...ALLOWED_KEYS].filter((k) => !Object.keys(ALIAS_KEYS).includes(k)).join(", ")}`,
 		);
 	}
 
-	// apiUrl: config wins, then env var, then local default
-	const apiUrl =
-		(typeof resolved.apiUrl === "string" && resolved.apiUrl.trim()) ||
-		(typeof process.env.NMEM_API_URL === "string" &&
-			process.env.NMEM_API_URL.trim()) ||
-		"";
+	const _sources = {};
+
+	// --- sessionContext: file > pluginConfig > env > default ---
+	const sc = firstDefined(
+		{ value: pickBool(resolvedFile, "sessionContext"), source: "file" },
+		{
+			value: pickBool(resolvedPlugin, "sessionContext"),
+			source: "pluginConfig",
+		},
+		{
+			value: envBool("NMEM_SESSION_CONTEXT", "NMEM_AUTO_RECALL"),
+			source: "env",
+		},
+		{ value: false, source: "default" },
+	);
+	const sessionContext = sc.value;
+	_sources.sessionContext = sc.source;
+
+	// --- sessionDigest: file > pluginConfig > env > default ---
+	const sd = firstDefined(
+		{ value: pickBool(resolvedFile, "sessionDigest"), source: "file" },
+		{
+			value: pickBool(resolvedPlugin, "sessionDigest"),
+			source: "pluginConfig",
+		},
+		{
+			value: envBool("NMEM_SESSION_DIGEST", "NMEM_AUTO_CAPTURE"),
+			source: "env",
+		},
+		{ value: true, source: "default" },
+	);
+	const sessionDigest = sd.value;
+	_sources.sessionDigest = sd.source;
+
+	// --- digestMinInterval: file > pluginConfig > env > default ---
+	const dmiEnv =
+		envInt("NMEM_DIGEST_MIN_INTERVAL") ?? envInt("NMEM_CAPTURE_MIN_INTERVAL");
+	const dmi = firstDefined(
+		{ value: pickNum(resolvedFile, "digestMinInterval"), source: "file" },
+		{
+			value: pickNum(resolvedPlugin, "digestMinInterval"),
+			source: "pluginConfig",
+		},
+		{ value: dmiEnv, source: "env" },
+		{ value: 300, source: "default" },
+	);
+	const digestMinInterval = Math.min(86400, Math.max(0, Math.trunc(dmi.value)));
+	_sources.digestMinInterval = dmi.source;
+
+	// --- maxContextResults: file > pluginConfig > env > default ---
+	const mcrEnv =
+		envInt("NMEM_MAX_CONTEXT_RESULTS") ?? envInt("NMEM_MAX_RECALL_RESULTS");
+	const mcr = firstDefined(
+		{ value: pickNum(resolvedFile, "maxContextResults"), source: "file" },
+		{
+			value: pickNum(resolvedPlugin, "maxContextResults"),
+			source: "pluginConfig",
+		},
+		{ value: mcrEnv, source: "env" },
+		{ value: 5, source: "default" },
+	);
+	const maxContextResults = Math.min(20, Math.max(1, Math.trunc(mcr.value)));
+	_sources.maxContextResults = mcr.source;
+
+	// --- apiUrl: file > pluginConfig > env > "" ---
+	const fileUrl =
+		typeof resolvedFile.apiUrl === "string" && resolvedFile.apiUrl.trim();
+	const pluginUrl =
+		typeof resolvedPlugin.apiUrl === "string" && resolvedPlugin.apiUrl.trim();
+	const au = firstDefined(
+		{ value: fileUrl || undefined, source: "file" },
+		{ value: pluginUrl || undefined, source: "pluginConfig" },
+		{ value: envStr("NMEM_API_URL"), source: "env" },
+		{ value: "", source: "default" },
+	);
+	const apiUrl = au.value;
+	_sources.apiUrl = au.source;
 
-	// apiKey: config wins, then env var — never logged, never in CLI args
-	const apiKey =
-		(typeof resolved.apiKey === "string" && resolved.apiKey.trim()) ||
-		(typeof process.env.NMEM_API_KEY === "string" &&
-			process.env.NMEM_API_KEY.trim()) ||
-		"";
+	// --- apiKey: file > pluginConfig > env > "" ---
+	const fileKey =
+		typeof resolvedFile.apiKey === "string" && resolvedFile.apiKey.trim();
+	const pluginKey =
+		typeof resolvedPlugin.apiKey === "string" && resolvedPlugin.apiKey.trim();
+	const ak = firstDefined(
+		{ value: fileKey || undefined, source: "file" },
+		{ value: pluginKey || undefined, source: "pluginConfig" },
+		{ value: envStr("NMEM_API_KEY"), source: "env" },
+		{ value: "", source: "default" },
+	);
+	const apiKey = ak.value;
+	_sources.apiKey = ak.source;
 
 	return {
-		sessionContext:
-			typeof resolved.sessionContext === "boolean"
-				? resolved.sessionContext
-				: false,
-		sessionDigest:
-			typeof resolved.sessionDigest === "boolean"
-				? resolved.sessionDigest
-				: true,
-		digestMinInterval:
-			typeof resolved.digestMinInterval === "number" &&
-			Number.isFinite(resolved.digestMinInterval)
-				? Math.min(86400, Math.max(0, Math.trunc(resolved.digestMinInterval)))
-				: 300,
-		maxContextResults:
-			typeof resolved.maxContextResults === "number" &&
-			Number.isFinite(resolved.maxContextResults)
-				? Math.min(20, Math.max(1, Math.trunc(resolved.maxContextResults)))
-				: 5,
+		sessionContext,
+		sessionDigest,
+		digestMinInterval,
+		maxContextResults,
 		apiUrl,
 		apiKey,
+		_sources,
 	};
 }

package/src/hooks/capture.js

@@ -291,7 +291,7 @@ export function buildAgentEndCaptureHandler(client, cfg, logger) {
 		});
 
 		// 2. Triage + distill: language-agnostic LLM-based capture.
-		//    Defensive guard — registration in index.js already gates on autoCapture,
+		//    Defensive guard - registration in index.js already gates on sessionDigest,
 		//    but check here too so the handler is safe if called directly.
 		if (!cfg.sessionDigest) return;
 

package/src/index.js

@@ -18,6 +18,7 @@ import { createForgetTool } from "./tools/forget.js";
 import { createMemoryGetTool } from "./tools/memory-get.js";
 import { createMemorySearchTool } from "./tools/memory-search.js";
 import { createSaveTool } from "./tools/save.js";
+import { createStatusTool } from "./tools/status.js";
 import { createThreadFetchTool } from "./tools/thread-fetch.js";
 import { createThreadSearchTool } from "./tools/thread-search.js";
 import { createTimelineTool } from "./tools/timeline.js";
@@ -30,8 +31,8 @@ export default {
 	kind: "memory",
 
 	register(api) {
-		const cfg = parseConfig(api.pluginConfig);
 		const logger = api.logger;
+		const cfg = parseConfig(api.pluginConfig, logger);
 		const client = new NowledgeMemClient(logger, {
 			apiUrl: cfg.apiUrl,
 			apiKey: cfg.apiKey,
@@ -52,6 +53,9 @@ export default {
 		api.registerTool(createThreadSearchTool(client, logger));
 		api.registerTool(createThreadFetchTool(client, logger));
 
+		// Diagnostics
+		api.registerTool(createStatusTool(client, logger, cfg));
+
 		// Always-on: behavioral guidance so the agent proactively saves and searches.
 		// Fires every turn via before_prompt_build — ~50 tokens, negligible cost.
 		// When sessionContext is on, guidance adjusts to avoid redundant searches.

package/src/tools/status.js

@@ -0,0 +1,145 @@
+/**
+ * nowledge_mem_status - verify config, connectivity, and backend health.
+ *
+ * Lets the user (or agent) confirm that apiUrl, apiKey, and other
+ * settings are taking effect, and that the backend is reachable.
+ * Shows where each config value comes from (file, pluginConfig, env, default).
+ */
+import { isDefaultApiUrl } from "../config.js";
+
+export function createStatusTool(client, _logger, cfg) {
+	return {
+		name: "nowledge_mem_status",
+		description:
+			"Check Nowledge Mem status: effective configuration, backend connectivity, and version. " +
+			"Call this when the user wants to verify their setup is working, " +
+			"especially after changing apiUrl or apiKey for remote mode.",
+		parameters: {
+			type: "object",
+			properties: {},
+		},
+		async execute() {
+			const lines = [];
+			const details = {};
+			const sources = cfg._sources || {};
+
+			// 1. Mode + connection target
+			const remote = !isDefaultApiUrl(cfg.apiUrl);
+			const mode = remote ? "remote" : "local";
+			details.mode = mode;
+			details.apiUrl = cfg.apiUrl || "http://127.0.0.1:14242";
+			details.apiKeySet = Boolean(cfg.apiKey);
+
+			lines.push(
+				`Mode: ${remote ? `Remote (${cfg.apiUrl})` : "Local (127.0.0.1:14242)"}`,
+			);
+			lines.push(`API key: ${cfg.apiKey ? "set" : "not set"}`);
+
+			// 2. CLI resolution
+			try {
+				const cmd = client.resolveCommand();
+				details.cli = cmd.join(" ");
+				lines.push(`CLI: ${cmd.join(" ")}`);
+			} catch {
+				details.cli = null;
+				lines.push("CLI: not found (install with: pip install nmem-cli)");
+			}
+
+			// 3. Backend health
+			let healthy = false;
+			try {
+				healthy = await client.checkHealth();
+			} catch {
+				// checkHealth already returns false on error
+			}
+			details.healthy = healthy;
+
+			if (healthy) {
+				lines.push("Backend: reachable");
+				// Fetch detailed health info
+				try {
+					const health = await client.apiJson(
+						"GET",
+						"/health",
+						undefined,
+						5000,
+					);
+					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
+				}
+			} else {
+				lines.push("Backend: not reachable");
+				if (remote) {
+					lines.push(
+						"  Check that apiUrl is correct and the server is running.",
+					);
+					if (!cfg.apiKey) {
+						lines.push("  Remote mode usually requires an API key.");
+					}
+				} else {
+					lines.push("  Ensure the Nowledge Mem desktop app is running.");
+				}
+			}
+
+			// 4. Effective config with sources
+			lines.push("");
+			lines.push("Config (source):");
+			lines.push(
+				`  sessionContext: ${cfg.sessionContext} (${sources.sessionContext || "?"})`,
+			);
+			lines.push(
+				`  sessionDigest: ${cfg.sessionDigest} (${sources.sessionDigest || "?"})`,
+			);
+			lines.push(
+				`  digestMinInterval: ${cfg.digestMinInterval}s (${sources.digestMinInterval || "?"})`,
+			);
+			lines.push(
+				`  maxContextResults: ${cfg.maxContextResults} (${sources.maxContextResults || "?"})`,
+			);
+
+			details.config = {
+				sessionContext: {
+					value: cfg.sessionContext,
+					source: sources.sessionContext,
+				},
+				sessionDigest: {
+					value: cfg.sessionDigest,
+					source: sources.sessionDigest,
+				},
+				digestMinInterval: {
+					value: cfg.digestMinInterval,
+					source: sources.digestMinInterval,
+				},
+				maxContextResults: {
+					value: cfg.maxContextResults,
+					source: sources.maxContextResults,
+				},
+				apiUrl: { value: cfg.apiUrl || "(local)", source: sources.apiUrl },
+				apiKey: {
+					value: cfg.apiKey ? "(set)" : "(not set)",
+					source: sources.apiKey,
+				},
+			};
+
+			lines.push("");
+			lines.push(
+				"Priority: config file > OpenClaw settings > env vars > defaults",
+			);
+
+			return {
+				content: [{ type: "text", text: lines.join("\n") }],
+				details,
+			};
+		},
+	};
+}