@nowledge/openclaw-nowledge-mem 0.8.35 → 0.8.39

package/CHANGELOG.md

@@ -4,6 +4,35 @@ All notable changes to the Nowledge Mem OpenClaw plugin will be documented in th
 
 ## Unreleased
 
+## [0.8.39] - 2026-10-18
+
+### Fixed
+
+- Schedule automatic distillation by stored thread ID, without the inline content removed in Mem 0.10.7.
+- Report background task acceptance instead of a synchronous memory count, and reject missing scheduling acknowledgements or an unavailable background scheduler.
+
+## [0.8.38] - 2026-10-17
+
+- Refresh the embedded core 0.2.0 content manifest for Alma adoption; runtime behavior is unchanged.
+
+## [0.8.37] - 2026-10-16
+
+- Embed shared TypeScript core 0.2.0, including the shared prefix-hashing API.
+- Reuse shared persistence acknowledgements and sync timeouts while retaining
+  OpenClaw message projection, compaction-shrink handling, legacy cursors, and
+  response-shape normalization. Reject unsafe acknowledgement counts.
+- Retain embedded-core receipts for both npm and ClawHub artifacts.
+
+
+## [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,14 +196,14 @@ 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. |
 
 ### Session Lifecycle (Automatic Capture)
 
-When sessions end, conversations are captured and optionally distilled. No user action needed.
+Conversations are captured during the session lifecycle. After positive triage, the plugin schedules background distillation of the saved thread. Task acceptance is logged immediately; extracted memories appear after the backend finishes the task. No user action needed.
 
 ```mermaid
 flowchart TD
@@ -216,7 +216,8 @@ flowchart TD
     C --> F{"sessionDigest enabled+ enough messages+ cooldown passed?"}
     F -->|"Yes"| G["LLM triage (~100 tokens):worth distilling?"]
     F -->|"No"| H["Done - thread saved"]
-    G -->|"Decisions, insights,preferences found"| I["Full distillation ->structured memories(with sourceThreadId)"]
+    G -->|"Decisions, insights,preferences found"| I["Schedule background distillation by thread ID"]
+    I --> J["Backend extracts structured memories(with sourceThreadId)"]
     G -->|"Routine chat"| H
 
     D --> H
@@ -226,21 +227,21 @@ flowchart TD
 **Key points:**
 - Thread capture is unconditional: every conversation is saved and searchable via `nowledge_mem_thread_search`
 - Thread sync is incremental: the plugin preserves the real transcript, appends only the unsynced tail, and requires Mem's checkpointed acknowledgement before the local cursor advances
-- LLM distillation only runs at `agent_end`, not during compaction/reset checkpoints
+- Distillation is scheduled from `agent_end` or Context Engine `afterTurn`, not during compaction/reset checkpoints
 - 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 +366,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 +645,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.39",
 	"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.39",
 	"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

@@ -849,25 +849,36 @@ export class NowledgeMemClient {
 	}
 
 	/**
-	 * Distill memories from a conversation thread.
-	 * Calls the full distillation endpoint which uses LLM to extract
-	 * structured memories (with unit_type, temporal data, labels).
+	 * Schedule background distillation of an already stored conversation thread.
+	 * Mem 0.10.7+ no longer accepts inline content for distillation.
+	 * The acknowledgement reports task acceptance, not completed memories.
 	 *
-	 * @param {{ threadId: string, title?: string, content: string }} params
+	 * @param {{ threadId: string, title?: string }} params
 	 */
-	async distillThread({ threadId, title, content }) {
-		return this.apiJson(
+	async distillThread({ threadId, title }) {
+		const normalizedThreadId = String(threadId || "").trim();
+		if (!normalizedThreadId) throw new Error("distillThread requires threadId");
+		const result = await this.apiJson(
 			"POST",
-			"/memories/distill",
+			"/memories/distill/schedule",
 			{
-				thread_id: String(threadId || ""),
+				thread_id: normalizedThreadId,
 				thread_title: title || "",
-				thread_content: String(content || ""),
 				distillation_type: "simple_llm",
 				extraction_level: "swift",
 			},
-			60_000, // 60s timeout for LLM distillation
 		);
+		if (
+			result?.success !== true ||
+			typeof result.task_id !== "string" ||
+			!result.task_id.trim()
+		) {
+			throw new Error("Distillation scheduling was not acknowledged with a task ID");
+		}
+		if (result.enqueued === false) {
+			throw new Error("Distillation background scheduler is unavailable");
+		}
+		return result;
 	}
 
 	// ── Thread search ────────────────────────────────────────────────────────
@@ -968,8 +979,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 +988,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/generated/plugin-core/acknowledgement.d.ts

@@ -0,0 +1,6 @@
+export declare function isThreadAppendAck(data: unknown): boolean;
+export declare function isCheckpointedAppendAck(data: unknown): boolean;
+export declare function appendAcknowledgedRemoteCount(data: unknown): number | undefined;
+export declare function isThreadCreateAck(data: unknown, expectedThreadId: string): boolean;
+export declare function createAcknowledgedRemoteCount(data: unknown, expectedThreadId: string): number | undefined;
+export declare function isCheckpointConflictResponse(data: unknown): boolean;

package/src/generated/plugin-core/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./thread-delta.js";
+export * from "./acknowledgement.js";
+export * from "./timeout.js";

package/src/generated/plugin-core/index.js

@@ -0,0 +1,92 @@
+// Generated from shared/plugin-core. Run npm --prefix shared/plugin-core run build.
+
+// src/thread-delta.ts
+import { createHash } from "node:crypto";
+function stableMessageFingerprint(message) {
+  return JSON.stringify(message);
+}
+function prefixFingerprint(messages, end, messageFingerprint) {
+  const hash = createHash("sha256");
+  for (const message of messages.slice(0, end)) {
+    const value = messageFingerprint(message);
+    hash.update(String(Buffer.byteLength(value)));
+    hash.update(":");
+    hash.update(value);
+  }
+  return hash.digest("hex");
+}
+function selectAcknowledgedDelta(messages, cursor, externalId, messageFingerprint = stableMessageFingerprint) {
+  let start = cursor?.count ?? 0;
+  const validCount = Number.isSafeInteger(start) && start >= 0 && start <= messages.length;
+  const prefixMatches = validCount && (start === 0 || externalId(messages[start - 1]) === cursor?.lastExternalId && prefixFingerprint(messages, start, messageFingerprint) === cursor?.prefixFingerprint);
+  const reset = !prefixMatches;
+  if (reset) start = 0;
+  const end = messages.length;
+  return {
+    start,
+    end,
+    messages: messages.slice(start),
+    next: {
+      count: end,
+      remoteCount: cursor?.remoteCount ?? end,
+      ...end > 0 ? { lastExternalId: externalId(messages[end - 1]) } : {},
+      prefixFingerprint: prefixFingerprint(messages, end, messageFingerprint)
+    },
+    reset
+  };
+}
+
+// src/acknowledgement.ts
+function record(value) {
+  return typeof value === "object" && value !== null;
+}
+function messageCount(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function isThreadAppendAck(data) {
+  return record(data) && data.success === true && messageCount(data.messages_added) && messageCount(data.total_messages);
+}
+function isCheckpointedAppendAck(data) {
+  return isThreadAppendAck(data) && data.append_mode === "checkpointed";
+}
+function appendAcknowledgedRemoteCount(data) {
+  return isThreadAppendAck(data) ? data.total_messages : void 0;
+}
+function isThreadCreateAck(data, expectedThreadId) {
+  return record(data) && record(data.thread) && data.thread.thread_id === expectedThreadId;
+}
+function createAcknowledgedRemoteCount(data, expectedThreadId) {
+  if (!isThreadCreateAck(data, expectedThreadId)) return void 0;
+  const result = data;
+  if (result.thread.message_count !== void 0) {
+    return messageCount(result.thread.message_count) ? result.thread.message_count : void 0;
+  }
+  return Array.isArray(result.messages) ? result.messages.length : void 0;
+}
+function isCheckpointConflictResponse(data) {
+  return record(data) && data.error_code === "checkpoint_conflict";
+}
+
+// src/timeout.ts
+var DEFAULT_THREAD_SYNC_TIMEOUT_MS = 12e4;
+var MIN_THREAD_SYNC_TIMEOUT_MS = 1e3;
+var MAX_THREAD_SYNC_TIMEOUT_MS = 30 * 6e4;
+function resolveThreadSyncTimeoutMs(raw) {
+  const parsed = Number(raw);
+  if (!raw?.trim() || !Number.isSafeInteger(parsed) || parsed <= 0) {
+    return DEFAULT_THREAD_SYNC_TIMEOUT_MS;
+  }
+  return Math.min(MAX_THREAD_SYNC_TIMEOUT_MS, Math.max(MIN_THREAD_SYNC_TIMEOUT_MS, parsed));
+}
+export {
+  appendAcknowledgedRemoteCount,
+  createAcknowledgedRemoteCount,
+  isCheckpointConflictResponse,
+  isCheckpointedAppendAck,
+  isThreadAppendAck,
+  isThreadCreateAck,
+  prefixFingerprint,
+  resolveThreadSyncTimeoutMs,
+  selectAcknowledgedDelta,
+  stableMessageFingerprint
+};

package/src/generated/plugin-core/manifest.json

@@ -0,0 +1,22 @@
+{
+  "schemaVersion": 1,
+  "core": {
+    "name": "@nowledge/plugin-core",
+    "version": "0.2.0",
+    "sourceDigest": "f06362cae4cdb5cd24a1eab4420860d41ab707f1558a25b779fcb3d74c651c56"
+  },
+  "build": {
+    "target": "es2022",
+    "format": "esm",
+    "esbuild": "0.25.9",
+    "typescript": "5.6.3"
+  },
+  "files": {
+    "acknowledgement.d.ts": "ffd0fd090f289c4deafba41d9faa83fb7f4a6070bd53588de5d1a947b076f65a",
+    "index.d.ts": "6e7965f903a043a34c3dd454f909e878134c1bf451ec7ff3c3026f035f1aaee0",
+    "index.js": "0e25a05abe9f9282dc6a7d3cc64a3da872c1e5192908308ee5086c0465f6c032",
+    "package.json": "609158e6c5fbc237939fa3ddf7faab80ab690bdc0c8d584414a885130103c4e8",
+    "thread-delta.d.ts": "83f31e3334086f6fdfe5e6e1b1c4b1a994bb6d49fda2fdedf450d14f4ec18cba",
+    "timeout.d.ts": "85bfd4185e9d0b22073250b5cbe19da38613d9af9fbc2022403ebb527dad9f8f"
+  }
+}

package/src/generated/plugin-core/package.json

@@ -0,0 +1,4 @@
+{
+  "private": true,
+  "type": "module"
+}

package/src/generated/plugin-core/thread-delta.d.ts

@@ -0,0 +1,17 @@
+export type AcknowledgedCursor = {
+    count: number;
+    remoteCount: number;
+    lastExternalId?: string;
+    prefixFingerprint: string;
+};
+export type AcknowledgedDelta<T> = {
+    start: number;
+    end: number;
+    messages: T[];
+    next: AcknowledgedCursor;
+    reset: boolean;
+};
+export declare function stableMessageFingerprint(message: unknown): string;
+export declare function prefixFingerprint<T>(messages: readonly T[], end: number, messageFingerprint: (message: T) => string): string;
+/** The returned cursor is a candidate; only persistence acknowledgement commits it. */
+export declare function selectAcknowledgedDelta<T>(messages: readonly T[], cursor: AcknowledgedCursor | undefined, externalId: (message: T) => string, messageFingerprint?: (message: T) => string): AcknowledgedDelta<T>;

package/src/generated/plugin-core/timeout.d.ts

@@ -0,0 +1 @@
+export declare function resolveThreadSyncTimeoutMs(raw: string | undefined): number;

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

@@ -742,7 +742,7 @@ async function persistMessages({
 
 /**
  * Build a plain-text conversation string from normalized messages.
- * Used as input for triage and distillation.
+ * Used as input for triage; distillation reads the stored thread.
  *
  * Per-message content is capped at MAX_DISTILL_MESSAGE_CHARS and the
  * total output at MAX_CONVERSATION_CHARS to keep LLM API payloads
@@ -823,15 +823,10 @@ export async function triageAndDistill({
 		const distillResult = await client.distillThread({
 			threadId: captureResult.threadId,
 			title: buildThreadTitle(ctx, captureResult.normalized),
-			content: conversationText,
 		});
 
-		const count =
-			distillResult?.memories_created ??
-			distillResult?.created_memories?.length ??
-			0;
 		logger.info(
-			`capture: distilled ${count} memories from ${captureResult.threadId}`,
+			`capture: scheduled background distillation for ${captureResult.threadId} (task ${distillResult.task_id})`,
 		);
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);

package/src/session-delta.js

@@ -1,4 +1,14 @@
 import { createHash } from "node:crypto";
+import {
+	createAcknowledgedRemoteCount,
+	prefixFingerprint as corePrefixFingerprint,
+} from "./generated/plugin-core/index.js";
+
+export {
+	isCheckpointConflictResponse,
+	isCheckpointedAppendAck,
+	isThreadAppendAck,
+} from "./generated/plugin-core/index.js";
 
 export function sessionSyncLaneKey(threadId, apiUrl, apiKey, spaceId) {
 	const destination = createHash("sha256")
@@ -24,54 +34,27 @@ export function prefixFingerprint(
 	end,
 	messageFingerprint = stableMessageFingerprint,
 ) {
-	const hash = createHash("sha256");
-	for (const message of messages.slice(0, end)) {
-		const value = messageFingerprint(message);
-		hash.update(String(Buffer.byteLength(value)));
-		hash.update(":");
-		hash.update(value);
-	}
-	return hash.digest("hex");
-}
-
-export function isThreadAppendAck(data) {
-	return (
-		data !== null &&
-		typeof data === "object" &&
-		data.success === true &&
-		Number.isInteger(data.messages_added) &&
-		data.messages_added >= 0 &&
-		Number.isInteger(data.total_messages) &&
-		data.total_messages >= 0
-	);
+	return corePrefixFingerprint(messages, end, messageFingerprint);
 }
 
 export function threadCreateAck(data, expectedThreadId) {
 	if (data === null || typeof data !== "object") return null;
 	const thread =
-		data.thread !== null && typeof data.thread === "object" ? data.thread : data;
+		data.thread !== null && typeof data.thread === "object"
+			? data.thread
+			: data;
 	const threadId = String(thread.thread_id ?? "").trim();
-	const totalMessages = thread.message_count ?? thread.total_messages;
-	if (
-		threadId !== String(expectedThreadId || "").trim() ||
-		!Number.isInteger(totalMessages) ||
-		totalMessages < 0
-	) {
-		return null;
-	}
-	return { threadId, totalMessages };
-}
-
-export function isCheckpointedAppendAck(data) {
-	return isThreadAppendAck(data) && data.append_mode === "checkpointed";
-}
-
-export function isCheckpointConflictResponse(data) {
-	return (
-		data !== null &&
-		typeof data === "object" &&
-		data.error_code === "checkpoint_conflict"
+	const totalMessages = createAcknowledgedRemoteCount(
+		{
+			thread: {
+				thread_id: threadId,
+				message_count: thread.message_count ?? thread.total_messages,
+			},
+		},
+		String(expectedThreadId || "").trim(),
 	);
+	if (totalMessages === undefined) return null;
+	return { threadId, totalMessages };
 }
 
 export function selectSnapshotDelta(
@@ -102,9 +85,7 @@ export function selectSnapshotDelta(
 		};
 	}
 	const acknowledgedPrefix =
-		start >= 0
-			? prefixFingerprint(messages, start, messageFingerprint)
-			: "";
+		start >= 0 ? prefixFingerprint(messages, start, messageFingerprint) : "";
 	const fingerprintTrusted = Boolean(cursor?.prefixFingerprint);
 	const externalIdTrusted = Boolean(cursor?.lastExternalId);
 	if (
@@ -134,7 +115,13 @@ export function selectSnapshotDelta(
 	};
 }
 
-export function contentBoundIdempotencyKey(prefix, threadId, start, end, fingerprint) {
+export function contentBoundIdempotencyKey(
+	prefix,
+	threadId,
+	start,
+	end,
+	fingerprint,
+) {
 	return `${prefix}:${threadId}:${start}-${end}:${fingerprint}`;
 }
 

package/src/thread-sync-timeout.js

@@ -1,14 +1 @@
-const DEFAULT_THREAD_SYNC_TIMEOUT_MS = 120_000;
-const MIN_THREAD_SYNC_TIMEOUT_MS = 1_000;
-const MAX_THREAD_SYNC_TIMEOUT_MS = 30 * 60_000;
-
-export function resolveThreadSyncTimeoutMs(raw) {
-	const parsed = Number(raw);
-	if (!String(raw ?? "").trim() || !Number.isSafeInteger(parsed) || parsed <= 0) {
-		return DEFAULT_THREAD_SYNC_TIMEOUT_MS;
-	}
-	return Math.min(
-		MAX_THREAD_SYNC_TIMEOUT_MS,
-		Math.max(MIN_THREAD_SYNC_TIMEOUT_MS, parsed),
-	);
-}
+export { resolveThreadSyncTimeoutMs } from "./generated/plugin-core/index.js";

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 } : {}),
 						})),
 					};
 				});