@nowledge/openclaw-nowledge-mem 0.6.2 → 0.6.6

package/src/config.js

@@ -1,3 +1,7 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
 export const API_DEFAULT_URL = "http://127.0.0.1:14242";
 
 /**
@@ -9,56 +13,257 @@ export function isDefaultApiUrl(url) {
 	return !trimmed || trimmed === API_DEFAULT_URL;
 }
 
+// Canonical config keys (new names).
 const ALLOWED_KEYS = new Set([
+	"sessionContext",
+	"sessionDigest",
+	"digestMinInterval",
+	"maxContextResults",
+	"apiUrl",
+	"apiKey",
+	// Legacy aliases — accepted but not advertised
 	"autoRecall",
 	"autoCapture",
 	"captureMinInterval",
 	"maxRecallResults",
-	"apiUrl",
-	"apiKey",
 ]);
 
-export function parseConfig(raw) {
-	const obj = raw && typeof raw === "object" ? raw : {};
+// Backward-compatible aliases (old names → new names).
+// Accepted silently so existing users' configs keep working.
+const ALIAS_KEYS = {
+	autoRecall: "sessionContext",
+	autoCapture: "sessionDigest",
+	captureMinInterval: "digestMinInterval",
+	maxRecallResults: "maxContextResults",
+};
+
+// --- config file ---------------------------------------------------------
+
+const CONFIG_DIR = join(homedir(), ".nowledge-mem");
+const CONFIG_PATH = join(CONFIG_DIR, "openclaw.json");
+
+const DEFAULT_CONFIG = {
+	sessionContext: false,
+	sessionDigest: true,
+	digestMinInterval: 300,
+	maxContextResults: 5,
+	apiUrl: "",
+	apiKey: "",
+};
+
+/**
+ * Read ~/.nowledge-mem/openclaw.json.
+ * On first run, creates the file seeded with values from pluginConfig
+ * (if any) — this migrates settings before OpenClaw strips them.
+ * Returns {} on any error — never crashes.
+ */
+function readConfigFile(logger, pluginCfg) {
+	try {
+		if (!existsSync(CONFIG_PATH)) {
+			// Seed from pluginConfig + env vars for migration.
+			// Users on older OpenClaw get their values written to the file
+			// BEFORE a future OpenClaw update can strip them.
+			const initial = { ...DEFAULT_CONFIG };
+			if (pluginCfg && typeof pluginCfg === "object") {
+				// Resolve aliases in pluginConfig for seeding
+				const resolved = { ...pluginCfg };
+				for (const [oldKey, newKey] of Object.entries(ALIAS_KEYS)) {
+					if (oldKey in resolved) {
+						if (!(newKey in resolved)) {
+							resolved[newKey] = resolved[oldKey];
+						}
+						delete resolved[oldKey];
+					}
+				}
 
-	// Strict: reject unknown keys so users catch typos immediately.
-	// If OpenClaw adds new platform-level keys that should pass through,
-	// add them to ALLOWED_KEYS rather than silently accepting anything.
-	const unknownKeys = Object.keys(obj).filter((k) => !ALLOWED_KEYS.has(k));
+				if (typeof resolved.sessionContext === "boolean")
+					initial.sessionContext = resolved.sessionContext;
+				if (typeof resolved.sessionDigest === "boolean")
+					initial.sessionDigest = resolved.sessionDigest;
+				if (
+					typeof resolved.digestMinInterval === "number" &&
+					Number.isFinite(resolved.digestMinInterval)
+				)
+					initial.digestMinInterval = resolved.digestMinInterval;
+				if (
+					typeof resolved.maxContextResults === "number" &&
+					Number.isFinite(resolved.maxContextResults)
+				)
+					initial.maxContextResults = resolved.maxContextResults;
+				if (typeof resolved.apiUrl === "string" && resolved.apiUrl.trim())
+					initial.apiUrl = resolved.apiUrl.trim();
+				// apiKey intentionally NOT written to disk — keep in env/pluginConfig only
+			}
+
+			mkdirSync(CONFIG_DIR, { recursive: true });
+			writeFileSync(
+				CONFIG_PATH,
+				JSON.stringify(initial, null, 2) + "\n",
+				"utf-8",
+			);
+			logger?.info?.(
+				`nowledge-mem: created config at ${CONFIG_PATH} — edit to customize`,
+			);
+			return { ...initial };
+		}
+		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 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) {
+			if (!(newKey in resolved)) {
+				resolved[newKey] = resolved[oldKey];
+			}
+			delete resolved[oldKey];
+		}
+	}
+	return resolved;
+}
+
+// -------------------------------------------------------------------------
+
+/**
+ * Parse plugin config with cascade:
+ *   pluginConfig > ~/.nowledge-mem/openclaw.json > env vars > defaults
+ *
+ * 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, pluginCfg);
+
+	// Resolve aliases in both sources
+	const resolvedPlugin = resolveAliases(pluginCfg);
+	const resolvedFile = resolveAliases(fileCfg);
+
+	// Strict: reject unknown keys in pluginConfig (typo catcher).
+	// File config is our own — validated by shape, no strict check needed.
+	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
+	// --- sessionContext ---
+	const sessionContext =
+		pickBool(resolvedPlugin, "sessionContext") ??
+		pickBool(resolvedFile, "sessionContext") ??
+		envBool("NMEM_SESSION_CONTEXT", "NMEM_AUTO_RECALL") ??
+		false;
+
+	// --- sessionDigest ---
+	const sessionDigest =
+		pickBool(resolvedPlugin, "sessionDigest") ??
+		pickBool(resolvedFile, "sessionDigest") ??
+		envBool("NMEM_SESSION_DIGEST", "NMEM_AUTO_CAPTURE") ??
+		true;
+
+	// --- digestMinInterval ---
+	const rawInterval =
+		pickNum(resolvedPlugin, "digestMinInterval") ??
+		pickNum(resolvedFile, "digestMinInterval") ??
+		envInt("NMEM_DIGEST_MIN_INTERVAL") ??
+		envInt("NMEM_CAPTURE_MIN_INTERVAL");
+	const digestMinInterval =
+		rawInterval !== undefined
+			? Math.min(86400, Math.max(0, Math.trunc(rawInterval)))
+			: 300;
+
+	// --- maxContextResults ---
+	const rawMax =
+		pickNum(resolvedPlugin, "maxContextResults") ??
+		pickNum(resolvedFile, "maxContextResults") ??
+		envInt("NMEM_MAX_CONTEXT_RESULTS") ??
+		envInt("NMEM_MAX_RECALL_RESULTS");
+	const maxContextResults =
+		rawMax !== undefined
+			? Math.min(20, Math.max(1, Math.trunc(rawMax)))
+			: 5;
+
+	// --- apiUrl: pluginConfig > file > env > "" ---
 	const apiUrl =
-		(typeof obj.apiUrl === "string" && obj.apiUrl.trim()) ||
-		(typeof process.env.NMEM_API_URL === "string" &&
-			process.env.NMEM_API_URL.trim()) ||
+		(typeof resolvedPlugin.apiUrl === "string" && resolvedPlugin.apiUrl.trim()) ||
+		(typeof resolvedFile.apiUrl === "string" && resolvedFile.apiUrl.trim()) ||
+		envStr("NMEM_API_URL") ||
 		"";
 
-	// apiKey: config wins, then env var — never logged, never in CLI args
+	// --- apiKey: pluginConfig > file > env > "" ---
 	const apiKey =
-		(typeof obj.apiKey === "string" && obj.apiKey.trim()) ||
-		(typeof process.env.NMEM_API_KEY === "string" &&
-			process.env.NMEM_API_KEY.trim()) ||
+		(typeof resolvedPlugin.apiKey === "string" && resolvedPlugin.apiKey.trim()) ||
+		(typeof resolvedFile.apiKey === "string" && resolvedFile.apiKey.trim()) ||
+		envStr("NMEM_API_KEY") ||
 		"";
 
 	return {
-		autoRecall: typeof obj.autoRecall === "boolean" ? obj.autoRecall : false,
-		autoCapture: typeof obj.autoCapture === "boolean" ? obj.autoCapture : false,
-		captureMinInterval:
-			typeof obj.captureMinInterval === "number" &&
-			Number.isFinite(obj.captureMinInterval)
-				? Math.min(86400, Math.max(0, Math.trunc(obj.captureMinInterval)))
-				: 300,
-		maxRecallResults:
-			typeof obj.maxRecallResults === "number" &&
-			Number.isFinite(obj.maxRecallResults)
-				? Math.min(20, Math.max(1, Math.trunc(obj.maxRecallResults)))
-				: 5,
+		sessionContext,
+		sessionDigest,
+		digestMinInterval,
+		maxContextResults,
 		apiUrl,
 		apiKey,
 	};

package/src/hooks/behavioral.js

@@ -0,0 +1,43 @@
+/**
+ * Always-on behavioral hook — injected via before_prompt_build on EVERY turn.
+ *
+ * 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.
+ *
+ * Cost: ~50 tokens per turn. Negligible.
+ *
+ * When sessionContext is enabled, guidance is adjusted to note that
+ * relevant memories are already injected — reducing redundant searches
+ * while keeping the save nudge and thread awareness.
+ */
+
+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.",
+	"</nowledge-mem-guidance>",
+].join("\n");
+
+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.",
+	"</nowledge-mem-guidance>",
+].join("\n");
+
+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 };
+	};
+}

package/src/hooks/capture.js

@@ -274,7 +274,7 @@ function buildConversationText(normalized) {
  * triage or distillation, since those are mid-session checkpoints.
  */
 export function buildAgentEndCaptureHandler(client, cfg, logger) {
-	const cooldownMs = (cfg.captureMinInterval ?? 300) * 1000;
+	const cooldownMs = (cfg.digestMinInterval ?? 300) * 1000;
 
 	return async (event, ctx) => {
 		if (!event?.success) return;
@@ -291,9 +291,9 @@ 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.autoCapture) return;
+		if (!cfg.sessionDigest) return;
 
 		//    Skip when no new messages were added (e.g. heartbeat re-sync).
 		if (!result || result.messagesAdded === 0) {

package/src/hooks/recall.js

@@ -44,7 +44,7 @@ export function buildRecallHandler(client, cfg, logger) {
 
 		// 2. Relevant memories — enriched with scoring signals and labels
 		try {
-			const results = await client.searchRich(prompt, cfg.maxRecallResults);
+			const results = await client.searchRich(prompt, cfg.maxContextResults);
 			if (results.length > 0) {
 				const lines = results.map((r) => {
 					const title = r.title || "(untitled)";

package/src/index.js

@@ -6,6 +6,7 @@ import {
 	createRememberCommand,
 } from "./commands/slash.js";
 import { isDefaultApiUrl, parseConfig } from "./config.js";
+import { buildBehavioralHook } from "./hooks/behavioral.js";
 import {
 	buildAgentEndCaptureHandler,
 	buildBeforeResetCaptureHandler,
@@ -17,6 +18,8 @@ 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 { createThreadFetchTool } from "./tools/thread-fetch.js";
+import { createThreadSearchTool } from "./tools/thread-search.js";
 import { createTimelineTool } from "./tools/timeline.js";
 
 export default {
@@ -27,8 +30,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,
@@ -45,12 +48,22 @@ export default {
 		api.registerTool(createTimelineTool(client, logger));
 		api.registerTool(createForgetTool(client, logger));
 
-		// Hooks
-		if (cfg.autoRecall) {
-			api.on("before_agent_start", buildRecallHandler(client, cfg, logger));
+		// Thread tools (progressive conversation retrieval)
+		api.registerTool(createThreadSearchTool(client, logger));
+		api.registerTool(createThreadFetchTool(client, logger));
+
+		// 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.
+		api.on("before_prompt_build", buildBehavioralHook(logger, cfg));
+
+		// Session context: inject Working Memory + recalled memories at prompt time.
+		if (cfg.sessionContext) {
+			api.on("before_prompt_build", buildRecallHandler(client, cfg, logger));
 		}
 
-		if (cfg.autoCapture) {
+		// Session digest: capture threads + LLM distillation at lifecycle events.
+		if (cfg.sessionDigest) {
 			const threadCaptureHandler = buildBeforeResetCaptureHandler(
 				client,
 				cfg,
@@ -75,7 +88,7 @@ export default {
 
 		const remoteMode = !isDefaultApiUrl(cfg.apiUrl);
 		logger.info(
-			`nowledge-mem: initialized (recall=${cfg.autoRecall}, capture=${cfg.autoCapture}, mode=${remoteMode ? `remote → ${cfg.apiUrl}` : "local"})`,
+			`nowledge-mem: initialized (context=${cfg.sessionContext}, digest=${cfg.sessionDigest}, mode=${remoteMode ? `remote → ${cfg.apiUrl}` : "local"})`,
 		);
 	},
 };

package/src/tools/forget.js

@@ -87,8 +87,9 @@ export function createForgetTool(client, logger) {
 					};
 				}
 
-				// Single high-confidence match — delete directly
-				if (results.length === 1 || results[0].score >= 0.85) {
+				// Auto-delete only when exactly one result with high confidence.
+				// Deletion is irreversible — if multiple matches exist, always ask.
+				if (results.length === 1 && results[0].score >= 0.85) {
 					const target = results[0];
 					try {
 						client.exec(["--json", "m", "delete", "-f", target.id]);
@@ -115,7 +116,7 @@ export function createForgetTool(client, logger) {
 					}
 				}
 
-				// Multiple candidates — return list for user to pick
+				// Multiple candidates or low confidence — return list for user to pick
 				const candidates = results.map(
 					(r, i) =>
 						`${i + 1}. ${r.title || "(untitled)"} (${(r.score * 100).toFixed(0)}%) — id: ${r.id}\n   ${r.content.slice(0, 100)}`,

package/src/tools/memory-get.js

@@ -135,19 +135,29 @@ export function createMemoryGetTool(client, logger) {
 					safeParams.lines,
 				);
 
+				// Thread provenance: link to the source conversation
+				const sourceThreadId =
+					memory.source_thread ??
+					memory.source_thread_id ??
+					memory.metadata?.source_thread_id ??
+					null;
+
+				const result = {
+					path,
+					memoryId,
+					title: memory.title || "(untitled)",
+					text: snippet.text,
+					startLine: snippet.startLine,
+					endLine: snippet.endLine,
+					totalLines: snippet.totalLines,
+				};
+				if (sourceThreadId) result.sourceThreadId = sourceThreadId;
+
 				return {
 					content: [
 						{
 							type: "text",
-							text: JSON.stringify({
-								path,
-								memoryId,
-								title: memory.title || "(untitled)",
-								text: snippet.text,
-								startLine: snippet.startLine,
-								endLine: snippet.endLine,
-								totalLines: snippet.totalLines,
-							}),
+							text: JSON.stringify(result),
 						},
 					],
 				};

package/src/tools/memory-search.js

@@ -19,6 +19,7 @@ export function createMemorySearchTool(client, logger) {
 			"Don't wait to be asked — if the conversation topic might have relevant history, search for it. " +
 			"Uses multi-signal scoring: semantic, BM25 keyword, label, graph & community signals, recency/importance decay. " +
 			"Returns snippets with memoryIds — pass a memoryId to nowledge_mem_connections for cross-topic synthesis or source provenance. " +
+			"Also returns relevant past conversation snippets (relatedThreads) when available. " +
 			"Supports bi-temporal filtering: event_date_from/to (when the fact HAPPENED), recorded_date_from/to (when it was SAVED). " +
 			"For browsing recent activity by day use nowledge_mem_timeline instead.",
 		parameters: {
@@ -140,22 +141,50 @@ export function createMemorySearchTool(client, logger) {
 					if (entry.eventEnd) result.eventEnd = entry.eventEnd;
 					if (entry.temporalContext)
 						result.temporalContext = entry.temporalContext;
+					// Thread provenance: link to the source conversation
+					if (entry.sourceThreadId)
+						result.sourceThreadId = entry.sourceThreadId;
 					return result;
 				});
 
+				// Enrich with thread snippets (best-effort, non-blocking)
+				let threadSnippets = [];
+				try {
+					const { threads } = await client.searchThreads(query, 3);
+					if (threads.length > 0) {
+						threadSnippets = threads.map((t) => {
+							const msgs = (t.matched_messages ?? []).slice(0, 2);
+							return {
+								threadId: t.thread_id ?? t.id,
+								title: t.title || "(untitled thread)",
+								source: t.source ?? "unknown",
+								lastActivity: t.last_activity ?? null,
+								relevanceScore: Number(t.relevance_score ?? 0),
+								matchedMessages: msgs.map((m) => ({
+									role: m.role,
+									snippet: truncateSnippet(m.snippet, 200),
+								})),
+							};
+						});
+					}
+				} catch {
+					// Thread search failure is not fatal
+				}
+
+				const responsePayload = {
+					results,
+					provider: "nmem",
+					mode: "multi-signal",
+				};
+				if (threadSnippets.length > 0) {
+					responsePayload.relatedThreads = threadSnippets;
+				}
+
 				return {
 					content: [
 						{
 							type: "text",
-							text: JSON.stringify(
-								{
-									results,
-									provider: "nmem",
-									mode: "multi-signal",
-								},
-								null,
-								2,
-							),
+							text: JSON.stringify(responsePayload, null, 2),
 						},
 					],
 					details: { query, resultCount: results.length },

package/src/tools/save.js

@@ -124,6 +124,39 @@ export function createSaveTool(client, logger) {
 				};
 			}
 
+			// Dedup check: search for near-identical existing memories before saving.
+			// Only blocks at very high similarity (≥0.9) to avoid false positives.
+			// Lower matches (0.7-0.9) are noted but allowed — the Knowledge Agent
+			// handles deeper dedup via EVOLVES chains in the background.
+			try {
+				const query = title || text.slice(0, 200);
+				const existing = await client.searchRich(query, 3);
+				if (existing.length > 0) {
+					const top = existing[0];
+					if (top.score >= 0.9) {
+						logger.info(
+							`save: skipped — near-identical memory exists: ${top.id} (${(top.score * 100).toFixed(0)}%)`,
+						);
+						return {
+							content: [
+								{
+									type: "text",
+									text: `Not saved — a near-identical memory already exists:\n"${top.title}" (id: ${top.id}, similarity: ${(top.score * 100).toFixed(0)}%)\nUse memory_get with id ${top.id} to read it.`,
+								},
+							],
+							details: {
+								skipped: true,
+								reason: "duplicate",
+								existingId: top.id,
+								similarity: top.score,
+							},
+						};
+					}
+				}
+			} catch {
+				// Dedup check is best-effort — never block saves on search failure
+			}
+
 			try {
 				const args = ["--json", "m", "add", text];
 				if (title) args.push("-t", title);