@nowledge/openclaw-nowledge-mem 0.2.7

package/src/tools/memory-get.js

@@ -0,0 +1,168 @@
+function sliceLines(text, from, lines) {
+	const allLines = String(text || "").split(/\r?\n/u);
+	const start = Math.max(1, Math.trunc(Number(from) || 1));
+	const maxLines = Math.max(1, Math.trunc(Number(lines) || allLines.length));
+	const startIdx = start - 1;
+	const endIdx = Math.min(allLines.length, startIdx + maxLines);
+	const selected = allLines.slice(startIdx, endIdx);
+	return {
+		text: selected.join("\n"),
+		startLine: start,
+		endLine: Math.max(start, start + selected.length - 1),
+		totalLines: allLines.length,
+	};
+}
+
+function parseMemoryId(pathValue) {
+	const value = String(pathValue || "").trim();
+	if (!value) return null;
+
+	const fromDeeplink = value.match(
+		/^nowledgemem:\/\/memory\/([a-zA-Z0-9_-]+)$/u,
+	);
+	if (fromDeeplink) return fromDeeplink[1];
+
+	if (/^[a-zA-Z0-9_-]{8,}$/u.test(value)) {
+		return value;
+	}
+
+	return null;
+}
+
+export function createMemoryGetTool(client, logger) {
+	return {
+		name: "memory_get",
+		description:
+			"Read a specific memory snippet by path from memory_search (nowledgemem://memory/<id>) or by raw memory ID.",
+		parameters: {
+			type: "object",
+			properties: {
+				path: {
+					type: "string",
+					description:
+						"Memory path from memory_search (nowledgemem://memory/<id>) or raw memory ID",
+				},
+				from: {
+					type: "number",
+					description: "Optional 1-based starting line number",
+				},
+				lines: {
+					type: "number",
+					description: "Optional number of lines to return",
+				},
+			},
+			required: ["path"],
+		},
+		async execute(_toolCallId, params) {
+			const safeParams = params && typeof params === "object" ? params : {};
+			const path = String(safeParams.path ?? "").trim();
+			if (!path) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: JSON.stringify({
+								path: "",
+								text: "",
+								error: "path is required",
+							}),
+						},
+					],
+				};
+			}
+
+			try {
+				const lowerPath = path.toLowerCase();
+				if (lowerPath === "memory.md" || lowerPath === "memory") {
+					const wm = await client.readWorkingMemory();
+					if (!wm.available) {
+						return {
+							content: [
+								{
+									type: "text",
+									text: JSON.stringify({
+										path,
+										text: "",
+										error: "Working Memory not available",
+									}),
+								},
+							],
+						};
+					}
+					const snippet = sliceLines(
+						wm.content,
+						safeParams.from,
+						safeParams.lines,
+					);
+					return {
+						content: [
+							{
+								type: "text",
+								text: JSON.stringify({
+									path,
+									text: snippet.text,
+									startLine: snippet.startLine,
+									endLine: snippet.endLine,
+									totalLines: snippet.totalLines,
+									source: "working-memory",
+								}),
+							},
+						],
+					};
+				}
+
+				const memoryId = parseMemoryId(path);
+				if (!memoryId) {
+					return {
+						content: [
+							{
+								type: "text",
+								text: JSON.stringify({
+									path,
+									text: "",
+									error:
+										"Unsupported path. Use memory_search result path (nowledgemem://memory/<id>).",
+								}),
+							},
+						],
+					};
+				}
+
+				const memory = await client.getMemory(memoryId);
+				const snippet = sliceLines(
+					memory.content ?? "",
+					safeParams.from,
+					safeParams.lines,
+				);
+
+				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,
+							}),
+						},
+					],
+				};
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err);
+				logger.error(`memory_get failed: ${message}`);
+				return {
+					content: [
+						{
+							type: "text",
+							text: JSON.stringify({ path, text: "", error: message }),
+						},
+					],
+				};
+			}
+		},
+	};
+}

package/src/tools/memory-search.js

@@ -0,0 +1,183 @@
+function truncateSnippet(text, maxChars = 700) {
+	const value = String(text || "").trim();
+	if (!value) return "";
+	if (value.length <= maxChars) return value;
+	return `${value.slice(0, maxChars)}…`;
+}
+
+function toMemoryPath(memoryId) {
+	return `nowledgemem://memory/${memoryId}`;
+}
+
+export function createMemorySearchTool(client, logger) {
+	return {
+		name: "memory_search",
+		description:
+			"Search the user's knowledge graph using a multi-signal scoring pipeline: " +
+			"semantic (embedding), BM25 keyword, label match, graph & community signals, and recency/importance decay — " +
+			"not just simple vector similarity. " +
+			"Finds prior work, decisions, preferences, and facts. " +
+			"Returns snippets with memoryIds. " +
+			"Pass a memoryId to nowledge_mem_connections for cross-topic synthesis or source provenance. " +
+			"Supports bi-temporal filtering: event_date_from/to (when the fact HAPPENED) and " +
+			"recorded_date_from/to (when it was SAVED). Format: YYYY, YYYY-MM, or YYYY-MM-DD. " +
+			"For browsing recent activity by day use nowledge_mem_timeline instead.",
+		parameters: {
+			type: "object",
+			properties: {
+				query: {
+					type: "string",
+					description: "Natural language query",
+				},
+				maxResults: {
+					type: "number",
+					description: "Max result count (1-20, default 5)",
+				},
+				minScore: {
+					type: "number",
+					description: "Optional score threshold in [0, 1]",
+				},
+				event_date_from: {
+					type: "string",
+					description:
+						"Filter by when the fact/event HAPPENED — e.g. '2024', '2024-Q1', '2024-03', '2024-03-15'",
+				},
+				event_date_to: {
+					type: "string",
+					description:
+						"Upper bound for event date (YYYY, YYYY-MM, or YYYY-MM-DD)",
+				},
+				recorded_date_from: {
+					type: "string",
+					description:
+						"Filter by when this memory was SAVED to Nowledge Mem (YYYY-MM-DD)",
+				},
+				recorded_date_to: {
+					type: "string",
+					description: "Upper bound for record date (YYYY-MM-DD)",
+				},
+			},
+			required: ["query"],
+		},
+		async execute(_toolCallId, params) {
+			const safeParams = params && typeof params === "object" ? params : {};
+			const query = String(safeParams.query ?? "").trim();
+			const maxResults = Math.min(
+				20,
+				Math.max(
+					1,
+					Math.trunc(
+						Number(safeParams.maxResults ?? safeParams.limit ?? 5) || 5,
+					),
+				),
+			);
+			const minScore = Number(safeParams.minScore);
+			const hasMinScore = Number.isFinite(minScore);
+
+			const eventDateFrom = safeParams.event_date_from
+				? String(safeParams.event_date_from).trim()
+				: undefined;
+			const eventDateTo = safeParams.event_date_to
+				? String(safeParams.event_date_to).trim()
+				: undefined;
+			const recordedDateFrom = safeParams.recorded_date_from
+				? String(safeParams.recorded_date_from).trim()
+				: undefined;
+			const recordedDateTo = safeParams.recorded_date_to
+				? String(safeParams.recorded_date_to).trim()
+				: undefined;
+
+			const hasTemporalFilter =
+				eventDateFrom || eventDateTo || recordedDateFrom || recordedDateTo;
+
+			if (!query) {
+				return {
+					content: [{ type: "text", text: JSON.stringify({ results: [] }) }],
+				};
+			}
+
+			try {
+				let rawResults;
+
+				if (hasTemporalFilter) {
+					// Bi-temporal path: filter by event or record time
+					const { memories } = await client.searchTemporal(query, {
+						limit: maxResults,
+						eventDateFrom,
+						eventDateTo,
+						recordedDateFrom,
+						recordedDateTo,
+					});
+					rawResults = memories;
+				} else {
+					// Always use the rich API path to get relevance_reason + full metadata
+					rawResults = await client.searchRich(query, maxResults);
+				}
+
+				const filtered = hasMinScore
+					? rawResults.filter((entry) => Number(entry.score ?? 0) >= minScore)
+					: rawResults;
+
+				const results = filtered.map((entry) => {
+					const path = toMemoryPath(entry.id);
+					const snippet = truncateSnippet(entry.content);
+					const lineCount = Math.max(1, snippet.split(/\r?\n/u).length);
+					const result = {
+						path,
+						startLine: 1,
+						endLine: lineCount,
+						score: Number(entry.score ?? 0),
+						title: entry.title || "(untitled)",
+						snippet,
+						memoryId: entry.id,
+					};
+					// Scoring transparency: show which signals fired
+					if (entry.relevanceReason)
+						result.matchedVia = entry.relevanceReason;
+					// Importance context
+					if (entry.importance !== undefined && entry.importance !== null)
+						result.importance = Number(entry.importance);
+					// Temporal metadata
+					if (entry.eventStart) result.eventStart = entry.eventStart;
+					if (entry.eventEnd) result.eventEnd = entry.eventEnd;
+					if (entry.temporalContext)
+						result.temporalContext = entry.temporalContext;
+					return result;
+				});
+
+				return {
+					content: [
+						{
+							type: "text",
+							text: JSON.stringify(
+								{
+									results,
+									provider: "nmem",
+									mode: "multi-signal",
+								},
+								null,
+								2,
+							),
+						},
+					],
+					details: { query, resultCount: results.length },
+				};
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err);
+				logger.error(`memory_search failed: ${message}`);
+				return {
+					content: [
+						{
+							type: "text",
+							text: JSON.stringify({
+								results: [],
+								disabled: true,
+								error: message,
+							}),
+						},
+					],
+				};
+			}
+		},
+	};
+}

package/src/tools/save.js

@@ -0,0 +1,179 @@
+/**
+ * nowledge_mem_save — structured knowledge capture.
+ *
+ * Unlike a generic "store text" tool, this captures knowledge with:
+ * - Type classification (8 unit types → typed nodes in the knowledge graph)
+ * - Labels (arbitrary tags for recall and filtering)
+ * - Temporal context (when the event happened, not just when it was saved)
+ *
+ * Reflects Nowledge Mem's v0.6 memory model where every memory is a
+ * rich typed node — not a flat text blob.
+ */
+
+const VALID_UNIT_TYPES = new Set([
+	"fact",
+	"preference",
+	"decision",
+	"plan",
+	"procedure",
+	"learning",
+	"context",
+	"event",
+]);
+
+export function createSaveTool(client, logger) {
+	return {
+		name: "nowledge_mem_save",
+		description:
+			"Save a new insight, decision, or fact to the user's permanent knowledge graph. " +
+			"Call this proactively — don't wait to be asked. If the conversation surfaces something worth keeping " +
+			"(a technical choice made, a preference stated, something learned, a plan formed, a tool discovered), save it. " +
+			"Specify unit_type to give the memory richer structure: " +
+			"decision (a choice made), learning (an insight gained), preference (user taste), " +
+			"fact (verified info), plan (future intent), procedure (how-to steps), event (something that happened). " +
+			"Use labels for topics/projects. Use event_start for when the event HAPPENED (not when it's saved).",
+		parameters: {
+			type: "object",
+			properties: {
+				text: {
+					type: "string",
+					description:
+						"The knowledge to save — be specific and self-contained. Write it as if explaining to your future self.",
+				},
+				title: {
+					type: "string",
+					description: "Short searchable title (50–60 chars ideal)",
+				},
+				unit_type: {
+					type: "string",
+					enum: [...VALID_UNIT_TYPES],
+					description:
+						"Type: fact (verified info) | preference (user taste) | decision (choice made) | " +
+						"plan (future intent) | procedure (how-to) | learning (insight gained) | " +
+						"context (background info) | event (something that happened)",
+				},
+				importance: {
+					type: "number",
+					description:
+						"0.8–1.0: critical decisions/breakthroughs. 0.5–0.7: useful insights. 0.3–0.4: minor notes.",
+				},
+				labels: {
+					type: "array",
+					items: { type: "string" },
+					description:
+						"Topic or project labels for this memory (e.g. [\"python\", \"infra\"]). Used in search filtering.",
+				},
+				event_start: {
+					type: "string",
+					description:
+						"When the event/fact HAPPENED — not when you're saving it. " +
+						"Format: YYYY, YYYY-MM, or YYYY-MM-DD. Example: '2024-03' for March 2024.",
+				},
+				event_end: {
+					type: "string",
+					description:
+						"End of the event period (for ranges). Same format as event_start.",
+				},
+				temporal_context: {
+					type: "string",
+					enum: ["past", "present", "future", "timeless"],
+					description:
+						"Temporal framing: past (already happened), present (ongoing), future (planned), timeless (always true).",
+				},
+			},
+			required: ["text"],
+		},
+		async execute(_toolCallId, params) {
+			const safeParams = params && typeof params === "object" ? params : {};
+			const text = String(safeParams.text ?? "").trim();
+			const title = safeParams.title ? String(safeParams.title).trim() : undefined;
+			const unitType =
+				typeof safeParams.unit_type === "string" &&
+				VALID_UNIT_TYPES.has(safeParams.unit_type)
+					? safeParams.unit_type
+					: undefined;
+			const hasImportance =
+				safeParams.importance !== undefined && safeParams.importance !== null;
+			const importance = hasImportance
+				? Math.min(1, Math.max(0, Number(safeParams.importance)))
+				: undefined;
+			const labels = Array.isArray(safeParams.labels)
+				? safeParams.labels
+						.map((l) => String(l).trim())
+						.filter((l) => l.length > 0)
+				: [];
+			const eventStart = safeParams.event_start
+				? String(safeParams.event_start).trim()
+				: undefined;
+			const eventEnd = safeParams.event_end
+				? String(safeParams.event_end).trim()
+				: undefined;
+			const temporalContext =
+				typeof safeParams.temporal_context === "string" &&
+				["past", "present", "future", "timeless"].includes(
+					safeParams.temporal_context,
+				)
+					? safeParams.temporal_context
+					: undefined;
+
+			if (!text) {
+				return {
+					content: [{ type: "text", text: "Cannot save empty memory." }],
+				};
+			}
+
+			try {
+				const args = ["--json", "m", "add", text];
+				if (title) args.push("-t", title);
+				if (importance !== undefined && Number.isFinite(importance)) {
+					args.push("-i", String(importance));
+				}
+				if (unitType) args.push("--unit-type", unitType);
+				for (const label of labels) args.push("-l", label);
+				if (eventStart) args.push("--event-start", eventStart);
+				if (eventEnd) args.push("--event-end", eventEnd);
+				if (temporalContext) args.push("--when", temporalContext);
+
+				const data = client.execJson(args);
+				const id = String(
+					data.id ?? data.memory?.id ?? data.memory_id ?? "created",
+				);
+
+				// Build human-readable confirmation
+				const typeLabel = unitType ? ` [${unitType}]` : "";
+				const labelStr =
+					labels.length > 0 ? ` · labels: ${labels.join(", ")}` : "";
+				const timeStr = eventStart
+					? ` · event: ${eventStart}${eventEnd ? `→${eventEnd}` : ""}`
+					: "";
+
+				logger.info(`save: stored memory ${id}${typeLabel}`);
+
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Saved${title ? `: ${title}` : ""}${typeLabel} (id: ${id})${labelStr}${timeStr}`,
+						},
+					],
+					details: {
+						id,
+						title,
+						unitType: data.unit_type || unitType,
+						importance,
+						labels: data.labels || labels,
+						eventStart,
+						eventEnd,
+						temporalContext,
+					},
+				};
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : String(err);
+				logger.error(`save failed: ${msg}`);
+				return {
+					content: [{ type: "text", text: `Failed to save: ${msg}` }],
+				};
+			}
+		},
+	};
+}