@nowledge/openclaw-nowledge-mem 0.8.35 → 0.8.36

package/CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to the Nowledge Mem OpenClaw plugin will be documented in th
 
 ## Unreleased
 
+## [0.8.36] - 2026-10-11
+
+### Fixed
+
+- Search first, inspect at most one small targeted thread range per question, and report evidence gaps rather than walking offsets.
+- Preserve explicit target ranges, progressive graph exploration and existing session capture.
+- Default thread reads to eight messages when no limit is supplied.
+- Preserve matched-message positions so late-thread evidence can be selected without page walking.
+
 ## [0.8.35] - 2026-10-08
 
 - Align ClawHub-first code-plugin install metadata with the supported host baseline.

package/CLAUDE.md

@@ -49,7 +49,7 @@ src/
     timeline.js         - activity feed: daily grouping, event_type filter, memoryId hints
     forget.js           - memory deletion by ID or search
     thread-search.js    - search past conversations by keyword
-    thread-fetch.js     - fetch full messages from a thread with pagination
+    thread-fetch.js     - read one small targeted message range (default 8)
 skills/
   memory-guide/
     SKILL.md            - agent behavioral skill: when/how to search, save, explore memory (auto-discovered by OpenClaw)
@@ -139,9 +139,9 @@ When `contextEngine` points elsewhere (or is absent), hooks handle everything. N
 - `nowledge_mem_timeline` - activity feed via `nmem f`. Groups by day. `event_type` filter. Exact date range via `date_from`/`date_to` (YYYY-MM-DD). Entries include `(id: <memoryId>)` for chaining to connections.
 - `nowledge_mem_forget` - delete by ID or fuzzy query.
 
-### Thread Tools (progressive conversation retrieval)
+### Thread Tools (bounded conversation retrieval)
 - `nowledge_mem_thread_search` - search past conversations by keyword. Returns threads with matched message snippets, relevance scores, and message counts. Supports `source` filter.
-- `nowledge_mem_thread_fetch` - fetch messages from a specific thread. Start with a small page, then use `offset` + `limit` for progressive retrieval only when more context is needed.
+- `nowledge_mem_thread_fetch` - read one small targeted message range from a specific thread. Choose the needed range from search results before the single read; use a known `offset` once and a small `limit` (default 8).
 
 ### Diagnostics
 - `nowledge_mem_status` - show plugin trust status, memory slot status, effective config (mode, apiUrl, apiKey set, sessionContext, sessionDigest, etc.), backend connectivity, and version. Checks `plugins.allow`: warns if set but plugin not included (loading blocked); shows tip if not set (plugin loads via `entries.enabled` but trust is implicit). Warns if the memory slot points to `memory-core` instead of `openclaw-nowledge-mem` (common after OpenClaw 3.22+ upgrade). No parameters.
@@ -216,7 +216,7 @@ Legacy aliases accepted silently in all sources for backward compat:
 | `nmem --json m delete <id>` | `client.execJson()` in forget.js | Delete |
 | `GET /threads/search?query=&limit=` | `client.searchThreads()` | Thread search enrichment (best-effort, API-only) |
 | `nmem --json t search <q> -n N` | `client.searchThreadsFull()` | Full thread search (CLI-first, API fallback) |
-| `nmem --json t show <id> -n N --offset O` | `client.fetchThread()` | Fetch thread messages with pagination |
+| `nmem --json t show <id> -n N --offset O` | `client.fetchThread()` | Read one small targeted message range (default 8) |
 
 All commands have API fallback for older CLI versions.
 
@@ -272,3 +272,9 @@ After bumping, commit inside the `community/` submodule, then stage the updated
 - Do NOT expose full WM overwrite from agents - section-level patch is the right granularity.
 - Do NOT add cloud dependencies to the core path.
 - Do NOT accept unknown config keys (strict parser in `config.js`).
+
+### Bounded thread reads
+
+Search memories or threads first, then choose the specific conversation and message range needed. Call `thread_fetch_messages`, a host thread-fetch tool, or `nmem --json t show` at most once per question, using a small message limit (for example 8) and a content limit of 1200 where supported. A known target range may use a nonzero offset once.
+
+Never loop over offsets to reconstruct a conversation. Do not raise `--content-limit` to compensate for a slow or incomplete read. Small output limits do not guarantee cheap server-side work on every deployed backend. If a read is slow, incomplete, fails or times out, stop, report the evidence gap, and refine the search rather than retrying pages. A later explicit user request for another range is a new bounded read; a routine “continue” is not permission to drain the thread.

package/README.md

@@ -196,7 +196,7 @@ The behavioral skill and always-on hook nudge the agent to **search before answe
 | "What was I doing last week?" | `nowledge_mem_timeline` | Activity feed grouped by day. Supports exact date ranges. |
 | "How is X connected to Y?" | `nowledge_mem_connections` | Graph walk: edges, entities, EVOLVES chains, document provenance. |
 | Need startup context or today's focus/priorities | `nowledge_mem_context` | Read Context Bundle when available, with Working Memory fallback. Supports Working Memory section-level patch. |
-| Memory has `sourceThreadId` | `nowledge_mem_thread_fetch` | Fetch full source conversation. Pagination via `offset` + `limit`. |
+| Memory has `sourceThreadId` | `nowledge_mem_thread_fetch` | Read one small targeted source-message range; do not walk offsets. |
 | "Find our discussion about X" | `nowledge_mem_thread_search` | Search past conversations by keyword. Returns matched snippets. |
 | "Forget X" | `nowledge_mem_forget` | Delete by ID or search query. |
 | "Is my setup working?" | `nowledge_mem_status` | Show effective config, backend connectivity, and version. |
@@ -230,17 +230,17 @@ flowchart TD
 - Distilled memories carry `sourceThreadId`, linking them back to the source conversation
 - Cooldown (`digestMinInterval`, default 300s) prevents burst distillation
 
-### Progressive Retrieval (Memory -> Thread -> Messages)
+### Targeted Retrieval (Memory -> Thread -> Messages)
 
 Memories distilled from conversations carry a `sourceThreadId`. This creates a retrieval chain:
 
 ```mermaid
 flowchart TD
     A["memory_search'PostgreSQL decision'"] --> B["Result includessourceThreadId"]
-    B --> C["nowledge_mem_thread_fetch(offset=0, limit=50)"]
-    C --> D["50 messageshasMore: true"]
-    D --> E["nowledge_mem_thread_fetch(offset=50, limit=50)"]
-    E --> F["Next page"]
+    B --> C["Choose one known target message range"]
+    C --> D["nowledge_mem_thread_fetch(offset=target, limit=8) once"]
+    D --> E["Answer from evidence or report the gap"]
+    E --> F["Refine search if specific evidence is still missing"]
 ```
 
 Direct conversation search also works:
@@ -365,15 +365,15 @@ last_n_days: 7
 
 **nowledge_mem_thread_search** - Search past conversations by keyword. Returns matched threads with message snippets and relevance scores. Use when the user asks about a past discussion or wants to find a conversation from a specific time.
 
-**nowledge_mem_thread_fetch** - Fetch full messages from a conversation thread with pagination. Pass a `sourceThreadId` from memory results or a `threadId` from thread search. Supports `offset` and `limit` for progressive retrieval of long conversations.
+**nowledge_mem_thread_fetch** - Read one small targeted message range. Pass a `sourceThreadId` from memory results or a `threadId` from thread search. Supports `offset` and `limit` (default 8); a known nonzero offset is valid once, not a reason to walk pages.
 
 ```
 threadId: "openclaw-db-arch-a1b2c3"
-offset: 0, limit: 50
+offset: 0, limit: 8
 -> Thread: "Database architecture discussion" (128 messages)
   [user] We need to decide on the database for task events...
   [assistant] Based on the requirements, PostgreSQL with JSONB...
-  ... (126 more messages, use offset=50 for next page)
+  ... (126 messages not shown; refine search for the specific evidence needed)
 ```
 
 ## Operating Modes
@@ -644,3 +644,9 @@ Run `nmem config client show` and confirm the effective URL and API key state. T
 ## License
 
 MIT
+
+### Bounded thread reads
+
+Search memories or threads first, then choose the specific conversation and message range needed. Call `thread_fetch_messages`, a host thread-fetch tool, or `nmem --json t show` at most once per question, using a small message limit (for example 8) and a content limit of 1200 where supported. A known target range may use a nonzero offset once.
+
+Never loop over offsets to reconstruct a conversation. Do not raise `--content-limit` to compensate for a slow or incomplete read. Small output limits do not guarantee cheap server-side work on every deployed backend. If a read is slow, incomplete, fails or times out, stop, report the evidence gap, and refine the search rather than retrying pages. A later explicit user request for another range is a new bounded read; a routine “continue” is not permission to drain the thread.

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.35",
+	"version": "0.8.36",
 	"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.35",
+	"version": "0.8.36",
 	"type": "module",
 	"description": "Nowledge Mem memory plugin for OpenClaw, local-first personal knowledge base",
 	"author": {

package/skills/memory-guide/SKILL.md

@@ -22,7 +22,7 @@ Use natural language queries. This is semantic search, not file search.
 
 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.
+When results include `relatedThreads`, use `nowledge_mem_thread_fetch` with the `threadId` for one small targeted message range. A known offset may select that range; do not advance through pages. Follow the bounded thread-read policy below.
 
 Bi-temporal filters narrow results by time:
 
@@ -52,7 +52,7 @@ Browse recent activity grouped by day. Filter by `event_type` or exact `date_fro
 
 ## 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.
+Find past conversations by keyword, then once for the specific messages needed fetch messages. Threads span all sources: this tool, other AI tools, browser capture, imports.
 
 ## Startup Context (nowledge_mem_context)
 
@@ -63,3 +63,9 @@ Read Context Bundle when identity, active space, active rules, or current priori
 - 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."
+
+### Bounded thread reads
+
+Search memories or threads first, then choose the specific conversation and message range needed. Call `thread_fetch_messages`, a host thread-fetch tool, or `nmem --json t show` at most once per question, using a small message limit (for example 8) and a content limit of 1200 where supported. A known target range may use a nonzero offset once.
+
+Never loop over offsets to reconstruct a conversation. Do not raise `--content-limit` to compensate for a slow or incomplete read. Small output limits do not guarantee cheap server-side work on every deployed backend. If a read is slow, incomplete, fails or times out, stop, report the evidence gap, and refine the search rather than retrying pages. A later explicit user request for another range is a new bounded read; a routine “continue” is not permission to drain the thread.

package/src/client.js

@@ -968,8 +968,8 @@ export class NowledgeMemClient {
 	}
 
 	/**
-	 * Fetch full messages from a specific thread.
-	 * Supports pagination for progressive retrieval of long conversations.
+	 * Read one small targeted message range from a specific thread.
+	 * A known target offset is supported; do not walk offsets to reconstruct a conversation.
 	 *
 	 * Uses CLI: `nmem --json t show <id> -n N --offset O`
 	 * Falls back to API: GET /threads/{id}
@@ -977,13 +977,13 @@ export class NowledgeMemClient {
 	 * @param {string} threadId  Thread ID
 	 * @param {{ offset?: number; limit?: number }} [options]
 	 */
-	async fetchThread(threadId, { offset = 0, limit = 50 } = {}) {
+	async fetchThread(threadId, { offset = 0, limit = 8 } = {}) {
 		const id = String(threadId || "").trim();
 		if (!id) throw new Error("fetchThread requires threadId");
 
 		const normalizedLimit = Math.min(
 			200,
-			Math.max(1, Math.trunc(Number(limit) || 50)),
+			Math.max(1, Math.trunc(Number(limit) || 8)),
 		);
 		const normalizedOffset = Math.max(0, Math.trunc(Number(offset) || 0));
 

package/src/hooks/behavioral.js

@@ -17,11 +17,13 @@
 
 import { ceState } from "../ce-state.js";
 
+const THREAD_READ_GUIDANCE = "When results include a sourceThreadId, use nowledge_mem_thread_fetch for at most one small targeted message range per question (for example 8 messages). Never loop over offsets or increase content limits. If the read is slow, incomplete or fails, stop, report the evidence gap and refine search.";
+
 export const BASE_GUIDANCE = [
 	"<nowledge-mem-guidance>",
 	"You have access to the user's personal knowledge graph (Nowledge Mem).",
 	"Search proactively with memory_search when past context would improve your answer. Do not wait to be asked. Use natural language queries, not file paths.",
-	"When results include a sourceThreadId, use nowledge_mem_thread_fetch for full conversation context.",
+	THREAD_READ_GUIDANCE,
 	"Save autonomously with nowledge_mem_save when the conversation produces a decision, preference, plan, procedure, or learning. Do not wait to be asked.",
 	"</nowledge-mem-guidance>",
 ].join("\n");
@@ -31,7 +33,7 @@ export const SESSION_CONTEXT_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 for specifics beyond what was auto-recalled, or when the user references prior work not covered above. Natural language queries, not file paths.",
-	"When results include a sourceThreadId, use nowledge_mem_thread_fetch for full conversation context.",
+	THREAD_READ_GUIDANCE,
 	"Save autonomously with nowledge_mem_save when the conversation produces a decision, preference, plan, procedure, or learning. Do not wait to be asked.",
 	"</nowledge-mem-guidance>",
 ].join("\n");

package/src/tools/memory-search.js

@@ -20,6 +20,7 @@ export function createMemorySearchTool(client, logger) {
 			"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. " +
+			"Use a matched messageIndex, when present, to choose one small targeted thread range; never walk offsets or invent missing positions. " +
 			"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: {
@@ -163,6 +164,8 @@ export function createMemorySearchTool(client, logger) {
 								matchedMessages: msgs.map((m) => ({
 									role: m.role,
 									snippet: truncateSnippet(m.snippet, 200),
+									...(Number.isInteger(m.message_index) && m.message_index >= 0
+										? { messageIndex: m.message_index } : {}),
 								})),
 							};
 						});

package/src/tools/thread-fetch.js

@@ -2,11 +2,11 @@ export function createThreadFetchTool(client, logger) {
 	return {
 		name: "nowledge_mem_thread_fetch",
 		description:
-			"Fetch full messages from a conversation thread. Use to read the complete context " +
+			"Fetch a targeted range of messages from a conversation thread. Use to read context " +
 			"around a memory — pass the sourceThreadId from memory_search or memory_get results, " +
 			"or a threadId from nowledge_mem_thread_search. " +
-			"Supports pagination for long conversations: set offset to skip earlier messages. " +
-			"Useful for progressive retrieval — fetch the first page, then request more if needed.",
+			"Use a known target offset to skip earlier messages once. " +
+			"Search first, then fetch at most one small targeted message range per question. Never loop over offsets to reconstruct a conversation or increase content limits. If the read is slow, incomplete or fails, stop, report the evidence gap and refine search.",
 		parameters: {
 			type: "object",
 			properties: {
@@ -17,11 +17,11 @@ export function createThreadFetchTool(client, logger) {
 				},
 				offset: {
 					type: "number",
-					description: "Skip first N messages (for pagination, default 0)",
+					description: "Known target message offset (default 0); never walk successive pages",
 				},
 				limit: {
 					type: "number",
-					description: "Max messages to return (1-200, default 50)",
+					description: "Max messages to return (1-200, default 8)",
 				},
 			},
 			required: ["threadId"],
@@ -35,7 +35,7 @@ export function createThreadFetchTool(client, logger) {
 			);
 			const limit = Math.min(
 				200,
-				Math.max(1, Math.trunc(Number(safeParams.limit ?? 50) || 50)),
+				Math.max(1, Math.trunc(Number(safeParams.limit ?? 8) || 8)),
 			);
 
 			if (!threadId) {

package/src/tools/thread-search.js

@@ -10,10 +10,12 @@ export function createThreadSearchTool(client, logger) {
 		name: "nowledge_mem_thread_search",
 		description:
 			"Search past conversations by keyword. Use when the user asks about a past discussion, " +
-			"wants to find a conversation from a specific time, or when you want to explore the full context " +
+			"wants to find a conversation from a specific time, or when you want to find relevant source messages " +
 			"around a topic beyond what memory_search returned. " +
 			"Returns matched threads with message snippets and relevance scores. " +
-			"To read full messages from a thread, pass its threadId to nowledge_mem_thread_fetch.",
+			"A match's messageIndex, when present, identifies a target offset for a nearby range; do not invent positions when absent. " +
+			"Pass its threadId to nowledge_mem_thread_fetch for at most one small targeted message range per question. " +
+			"Never loop over offsets; on slow, incomplete or failed reads, report the evidence gap and refine search.",
 		parameters: {
 			type: "object",
 			properties: {
@@ -74,6 +76,8 @@ export function createThreadSearchTool(client, logger) {
 						matchedMessages: msgs.map((m) => ({
 							role: m.role,
 							snippet: truncateSnippet(m.snippet),
+							...(Number.isInteger(m.message_index) && m.message_index >= 0
+								? { messageIndex: m.message_index } : {}),
 						})),
 					};
 				});