@nowledge/openclaw-nowledge-mem 0.6.2 → 0.6.5

package/CHANGELOG.md

@@ -2,6 +2,76 @@
 
 All notable changes to the Nowledge Mem OpenClaw plugin will be documented in this file.
 
+## [0.6.5] - 2026-02-26
+
+### Added — Thread tools + sourceThreadId linkage
+
+**Two new tools for conversation retrieval.** The plugin now provides 9 tools total.
+
+- `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 specific conversation.
+- `nowledge_mem_thread_fetch` — Fetch full messages from a specific thread with pagination support. Use to progressively retrieve long conversations. Accepts `offset` and `limit` for paginated retrieval.
+
+**Memories now link back to their source conversations.**
+
+Every memory distilled from a conversation now includes `sourceThreadId` in search results (`memory_search`) and individual lookups (`memory_get`). This enables the progressive retrieval workflow: search memories, see which thread they came from, fetch the full conversation for context.
+
+**New client methods:**
+
+- `client.searchThreadsFull(query, { limit, source })` — Full-featured thread search (throws on error, supports source filter). CLI-first with API fallback.
+- `client.fetchThread(threadId, { offset, limit })` — Fetch messages from a thread with pagination. CLI-first with API fallback.
+
+**Save deduplication.**
+
+Before saving, the plugin checks for near-identical existing memories (≥90% similarity). If a match is found, the save is skipped and the existing memory is returned — preventing obvious duplicates at the plugin level. Deeper semantic dedup is handled by the Knowledge Agent's EVOLVES chains in the background.
+
+**Context-aware behavioral guidance.**
+
+The always-on hook now tells the agent about `nowledge_mem_thread_fetch` for following up on `sourceThreadId` links. When `sessionContext` is enabled, the guidance adjusts to note that relevant memories have already been injected — reducing redundant `memory_search` calls.
+
+## [0.6.4] - 2026-02-26
+
+### Changed — Thread search enrichment + sessionDigest default on
+
+**`memory_search` now includes relevant conversation threads.**
+
+When you search memories, the response now also includes `relatedThreads` — snippets from past conversations that match the query. This uses the backend's BM25 thread search (`GET /threads/search`). Thread search is best-effort: if it fails or returns nothing, the memory results are returned as before. No new tool for the agent to learn — thread context surfaces automatically alongside memories.
+
+**`sessionDigest` now defaults to `true`.**
+
+Previously, session digest (thread capture + LLM distillation at session end) was off by default. The cost is negligible — one lightweight triage call per session end, full distillation only when worthwhile. With this change, conversations are captured and distilled automatically out of the box. Users who explicitly set `sessionDigest: false` are unaffected.
+
+**Behavioral hook updated.**
+
+The always-on guidance now mentions that `memory_search` returns conversation snippets alongside memories, so the agent knows to use the enriched results.
+
+### Added
+
+- `client.searchThreads(query, limit)` — calls `GET /threads/search` API. Returns top matching threads with message snippets and relevance scores. Best-effort: never throws.
+- Version bumped to 0.6.4.
+
+## [0.4.0] - 2026-02-26
+
+### Changed — Rename config + always-on behavioral guidance
+
+**Renamed config options** (old names still work as silent aliases):
+
+| Old name | New name |
+|----------|----------|
+| `autoRecall` | `sessionContext` |
+| `autoCapture` | `sessionDigest` |
+| `captureMinInterval` | `digestMinInterval` |
+| `maxRecallResults` | `maxContextResults` |
+
+Existing configs with old names continue to work — aliases are resolved transparently in `parseConfig()`. New names take precedence if both are present.
+
+**Added: Always-on behavioral hook**
+
+The agent now receives brief behavioral guidance (~50 tokens) on every turn via `before_prompt_build`, telling it to proactively save and search. This fires in ALL modes, including tool-only (default). Previously, without `sessionContext` enabled, the agent had no system-level instruction to use memory tools — most LLMs ignored the "call proactively" hints in tool descriptions. This is the single most impactful change for memory adoption.
+
+**Migrated: `before_prompt_build` for session context**
+
+Session context injection (formerly "autoRecall") now uses the modern `before_prompt_build` hook instead of legacy `before_agent_start`. Both the behavioral hook and session context coexist — OpenClaw concatenates multiple `prependContext` values with `\n\n`.
+
 ## [0.3.0] - 2026-02-23
 
 ### Changed — Architecture overhaul: tool-first, LLM-based capture

package/CLAUDE.md

@@ -28,26 +28,29 @@ Reflects Nowledge Mem's genuine v0.6 strengths:
 src/
   index.js          — plugin registration (tools, hooks, commands, CLI)
   client.js         — CLI wrapper with API fallback; credential handling
-  config.js         — strict config parsing (apiUrl, apiKey, autoRecall, etc.)
+  config.js         — strict config parsing (apiUrl, apiKey, sessionContext, etc.)
   hooks/
-    recall.js       — before_agent_start: inject Working Memory + recalled memories
-    capture.js      — quality-gated memory note + thread append
+    behavioral.js   — always-on behavioral guidance (~50 tokens/turn)
+    recall.js       — before_prompt_build: inject Working Memory + recalled memories
+    capture.js      — thread capture + LLM triage/distillation at session lifecycle events
   tools/
-    memory-search.js    — OpenClaw compat; multi-signal; bi-temporal; relevance_reason
-    memory-get.js       — OpenClaw compat; supports MEMORY.md alias
-    save.js             — structured capture: unit_type, labels, temporal, importance
-    context.js          — Working Memory daily briefing (read-only)
+    memory-search.js    — OpenClaw compat; multi-signal; bi-temporal; relevance_reason; sourceThreadId
+    memory-get.js       — OpenClaw compat; supports MEMORY.md alias; sourceThreadId
+    save.js             — structured capture: unit_type, labels, temporal, importance; pre-save dedup check
+    context.js          — Working Memory daily briefing (read + section-level patch)
     connections.js      — graph exploration: edge types, relationship strength, provenance
     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
 openclaw.plugin.json — manifest + config schema (version, uiHints, configSchema)
 ```
 
-## Tool Surface (7 tools)
+## Tool Surface (9 tools)
 
 ### OpenClaw Memory Slot (required for system prompt activation)
-- `memory_search` — multi-signal: BM25 + embedding + label + graph + decay. Returns `matchedVia` ("Text Match 100% + Semantic 69%"), `importance`, bi-temporal filters (`event_date_from/to`, `recorded_date_from/to`). Mode: `"multi-signal"`.
-- `memory_get` — retrieve by `nowledgemem://memory/<id>` path or bare ID. `MEMORY.md` → Working Memory.
+- `memory_search` — multi-signal: BM25 + embedding + label + graph + decay. Returns `matchedVia` ("Text Match 100% + Semantic 69%"), `importance`, bi-temporal filters (`event_date_from/to`, `recorded_date_from/to`). Also returns `relatedThreads` (past conversation snippets matching the query) and `sourceThreadId` (link to source conversation). Mode: `"multi-signal"`.
+- `memory_get` — retrieve by `nowledgemem://memory/<id>` path or bare ID. `MEMORY.md` → Working Memory. Returns `sourceThreadId` when available.
 
 ### Nowledge Mem Native (differentiators)
 - `nowledge_mem_save` — structured capture: `unit_type`, `labels[]`, `event_start`, `event_end`, `temporal_context`, `importance`. All fields wired to CLI and API.
@@ -56,10 +59,15 @@ openclaw.plugin.json — manifest + config schema (version, uiHints, configSchem
 - `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)
+- `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 full messages from a specific thread. Supports pagination via `offset` + `limit` for progressive retrieval of long conversations.
+
 ## Hook Surface
 
-- `before_agent_start` — auto-recall: Working Memory + `searchRich()` with `relevanceReason` in context
-- `agent_end` — quality-gated memory note + thread append (requires `autoCapture: true`)
+- `before_prompt_build` (always-on) — behavioral guidance: brief note telling agent to save/search proactively. Adjusts when sessionContext is on to avoid redundant searches.
+- `before_prompt_build` (sessionContext) — session context: Working Memory + `searchRich()` with `relevanceReason` in context
+- `agent_end` — thread capture + LLM triage/distillation (requires `sessionDigest: true`)
 - `after_compaction` — thread append
 - `before_reset` — thread append
 
@@ -73,9 +81,10 @@ openclaw.plugin.json — manifest + config schema (version, uiHints, configSchem
 
 | Key | Type | Default | Description |
 |-----|------|---------|-------------|
-| `autoRecall` | boolean | `false` | Inject context at session start |
-| `autoCapture` | boolean | `false` | Capture notes/threads at session end |
-| `maxRecallResults` | integer 1–20 | `5` | How many memories to recall |
+| `sessionContext` | boolean | `false` | Inject Working Memory + relevant memories at prompt time |
+| `sessionDigest` | boolean | `true` | Thread capture + LLM distillation at session end |
+| `maxContextResults` | integer 1–20 | `5` | How many memories to inject at prompt time |
+| `digestMinInterval` | integer | `300` | Minimum seconds between session digests |
 | `apiUrl` | string | `""` | Remote server URL. Empty = local (127.0.0.1:14242) |
 | `apiKey` | string | `""` | API key. Injected as `NMEM_API_KEY` env var only. Never logged. |
 
@@ -98,6 +107,9 @@ openclaw.plugin.json — manifest + config schema (version, uiHints, configSchem
 | `nmem --json wm read` | `client.readWorkingMemory()` | Working Memory read |
 | `nmem --json wm patch --heading "## S" --content/--append` | `client.patchWorkingMemory()` | Section-level WM update |
 | `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> --limit N` | `client.searchThreadsFull()` | Full thread search (CLI-first, API fallback) |
+| `nmem --json t show <id> --limit N --offset O` | `client.fetchThread()` | Fetch thread messages with pagination |
 
 All commands have API fallback for older CLI versions.
 

package/README.md

@@ -32,7 +32,7 @@ Start Nowledge Mem desktop app or run `nmem serve`, then configure:
 }
 ```
 
-That's it. The agent gets 7 tools and calls them on demand. No extra tokens wasted.
+That's it. The agent gets 9 tools and calls them on demand. No extra tokens wasted.
 
 ### Remote mode
 
@@ -57,15 +57,138 @@ Connect to a Nowledge Mem server running elsewhere — on a VPS, a home server,
 
 The `apiKey` is injected as `NMEM_API_KEY` into the nmem CLI process — never passed as a CLI argument, never logged.
 
+## How It Works
+
+### Per-Turn Flow
+
+Every user message triggers hooks before the agent sees it, then the agent decides which tools to call.
+
+```mermaid
+flowchart TD
+    A["User sends message"] --> B["before_prompt_build hook"]
+
+    B --> C["Behavioral guidance(always, ~110 tokens)"]
+    B -.->|"sessionContext: true"| D["Working Memory +relevant memories (~1-2 KB)"]
+
+    C --> E["Agent processes message(9 tools available)"]
+    D --> E
+
+    E --> F{"Needs past context?"}
+    F -->|"Yes"| G["memory_search"]
+    G --> R
+
+    E --> H{"Something worth keeping?"}
+    H -->|"Yes"| I["nowledge_mem_save(typed, labeled, temporal)"]
+    I --> R
+
+    E --> R["Respond to user"]
+```
+
+### When Each Tool Gets Called
+
+The behavioral hook nudges the agent to **search before answering** and **save after deciding**. Here's when each tool fires:
+
+| Scenario | Tool | What happens |
+|----------|------|--------------|
+| User asks a question | `memory_search` | Search knowledge base before answering. Also returns `relatedThreads` snippets and `sourceThreadId`. |
+| Agent needs full memory text | `memory_get` | Read one memory by ID or path. `MEMORY.md` alias reads Working Memory. Returns `sourceThreadId`. |
+| Decision made, insight learned | `nowledge_mem_save` | Structured save with `unit_type`, `labels`, `event_start`, `importance`. |
+| "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 today's focus/priorities | `nowledge_mem_context` | Read Working Memory daily briefing. Supports section-level patch. |
+| Memory has `sourceThreadId` | `nowledge_mem_thread_fetch` | Fetch full source conversation. Pagination via `offset` + `limit`. |
+| "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. |
+
+### Session Lifecycle (Automatic Capture)
+
+When sessions end, conversations are captured and optionally distilled. No user action needed.
+
+```mermaid
+flowchart TD
+    A["Session lifecycle event"] --> B{"Event type"}
+
+    B -->|"agent_end"| C["Append messages to thread(idempotent, deduped)"]
+    B -->|"after_compaction"| D["Append messages to thread(checkpoint only)"]
+    B -->|"before_reset"| E["Append messages to thread(checkpoint only)"]
+
+    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 -->|"Routine chat"| H
+
+    D --> H
+    E --> H
+```
+
+**Key points:**
+- Thread capture is **unconditional** — every conversation is saved and searchable via `nowledge_mem_thread_search`
+- LLM distillation only runs at `agent_end`, 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)
+
+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"]
+```
+
+Direct conversation search also works:
+
+```mermaid
+flowchart LR
+    G["nowledge_mem_thread_search 'database architecture'"] --> H["Threads with matched snippets"]
+    H --> I["nowledge_mem_thread_fetch(threadId from results)"]
+    I --> J["Full messages"]
+```
+
+Two entry points:
+1. **From a memory** — `memory_search` or `memory_get` returns `sourceThreadId` -> fetch the source conversation
+2. **Direct search** — `nowledge_mem_thread_search` finds conversations by keyword -> fetch any result
+
+### Three Modes at a Glance
+
+```mermaid
+flowchart LR
+    subgraph "default" ["Default (recommended)"]
+        direction TB
+        D1["Every turn: behavioral guidance (~50 tokens)"]
+        D2["Agent calls 9 tools on demand"]
+        D3["Session end: thread capture + LLM distillation"]
+    end
+
+    subgraph context ["Session Context"]
+        direction TB
+        C1["Every turn: guidance + Working Memory+ recalled memories (~1-2 KB)"]
+        C2["Agent calls 9 tools on demand"]
+        C3["Session end: thread capture + LLM distillation"]
+    end
+
+    subgraph minimal ["Minimal"]
+        direction TB
+        M1["Every turn: behavioral guidance (~50 tokens)"]
+        M2["Agent calls 9 tools on demand"]
+        M3["No automatic capture"]
+    end
+```
+
 ## Tools
 
 ### OpenClaw Memory Compatibility
 
 These satisfy the OpenClaw memory slot contract and activate the "Memory Recall" section in OpenClaw's system prompt.
 
-**memory_search** — Multi-signal recall using embedding, BM25, label match, graph signals, and recency decay. Returns structured source paths (`nowledgemem://memory/<id>`) for follow-up with `memory_get` or `nowledge_mem_connections`.
+**memory_search** — Multi-signal recall using embedding, BM25, label match, graph signals, and recency decay. Returns structured source paths (`nowledgemem://memory/<id>`) for follow-up with `memory_get` or `nowledge_mem_connections`. Also returns relevant past conversation snippets (`relatedThreads`) and `sourceThreadId` (link to the conversation the memory was distilled from) when available.
 
-**memory_get** — Read a specific memory by ID or path. Supports `MEMORY.md` alias for Working Memory.
+**memory_get** — Read a specific memory by ID or path. Supports `MEMORY.md` alias for Working Memory. Returns `sourceThreadId` when the memory was distilled from a conversation.
 
 ### Nowledge Mem Native
 
@@ -118,21 +241,44 @@ last_n_days: 7
 
 **nowledge_mem_forget** — Delete a memory by ID or search query. Supports user confirmation when multiple matches are found.
 
+### Thread Tools
+
+**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.
+
+```
+threadId: "openclaw-db-arch-a1b2c3"
+offset: 0, limit: 50
+-> 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)
+```
+
 ## Operating Modes
 
-The plugin supports three modes. The default (tool-only) gives the agent full access to all tools with zero token overhead.
+The plugin supports three modes. Choose based on how much you want to guarantee versus how much token budget you're willing to spend.
+
+| Mode | Config | Behavior | Tradeoff |
+|------|--------|----------|----------|
+| **Default** (recommended) | `sessionContext: false, sessionDigest: true` | Agent calls 9 tools on demand. Behavioral guidance every turn (~50 tokens). Conversations captured + distilled at session end. | Lowest cost. Agent decides when to search — usually smart, occasionally forgets. |
+| **Session context** | `sessionContext: true` | Working Memory + relevant memories injected at prompt time, plus all 9 tools still available. | ~1-2 KB/turn. Guarantees context is always present. Best for short sessions or critical workflows. |
+| **Minimal** | `sessionDigest: false` | Tool-only, no automatic capture. | Zero overhead beyond guidance. Use when you handle memory manually. |
+
+**Which mode should you use?**
+
+- **Most users**: start with default. The agent gets behavioral guidance nudging it to search before answering and save after deciding. It works well for most conversations.
+- **Short sessions or critical accuracy**: enable `sessionContext`. This guarantees relevant memories are present from the first turn — the agent doesn't need to decide whether to search. The tradeoff is ~1-2 KB of context per turn.
+- **Full manual control**: set `sessionDigest: false`. You control what gets saved (via `/remember` or `nowledge_mem_save`) and nothing is captured automatically.
 
-| Mode | Config | Behavior |
-|------|--------|----------|
-| **Tool-only** (default) | `autoRecall: false, autoCapture: false` | Agent calls tools on demand. Zero overhead. |
-| **Auto-recall** | `autoRecall: true` | Working Memory + relevant memories injected at session start. |
-| **Auto-capture** | `autoCapture: true` | Thread capture + LLM distillation at session end. |
+### Session Context (`sessionContext`, default: false)
 
-### Auto-Recall (`autoRecall`, default: false)
+When enabled, the plugin injects Working Memory and relevant search results at prompt time. The behavioral guidance automatically adjusts to tell the agent that context is already present — use `memory_search` only for specific follow-up queries, not broad recall. This prevents the agent from redundantly searching for the same context that was just injected.
 
-When enabled, the plugin injects Working Memory and relevant search results at session start. Useful for giving the agent immediate context without waiting for it to search proactively.
+Useful for giving the agent immediate context without waiting for it to search proactively.
 
-### Auto-Capture (`autoCapture`, default: false)
+### Session Digest (`sessionDigest`, default: true)
 
 When enabled, two things happen at `agent_end`, `after_compaction`, and `before_reset`:
 
@@ -140,6 +286,30 @@ When enabled, two things happen at `agent_end`, `after_compaction`, and `before_
 
 **2. LLM distillation (when worthwhile).** A lightweight LLM triage determines if the conversation has save-worthy content. If yes, a full distillation pass creates structured memories with types, labels, and temporal data. Language-agnostic — works in any language.
 
+## Design Decisions
+
+Honest answers to common questions about how the memory system works.
+
+**Does the agent always search before answering?**
+
+No. The behavioral guidance nudges the agent to search, but doesn't force it. This is a deliberate tradeoff — forcing a search on every turn would add latency and cost for messages that don't need past context (like "hello" or "thanks"). In practice, modern LLMs follow behavioral guidance reliably for knowledge-related questions. If guaranteed recall matters for your use case, enable `sessionContext: true` — that injects relevant memories at prompt time, before the agent even processes your message.
+
+**What stops the agent from saving duplicate memories?**
+
+Two layers. First, the plugin checks for near-identical existing memories before every save. If a memory with ≥90% similarity already exists, the save is skipped and the existing memory is returned instead. Second, Nowledge Mem's Knowledge Agent runs in the background and handles deeper deduplication — it identifies semantic overlap across memories and links them via EVOLVES chains (replaces, enriches, confirms, or challenges). The plugin handles obvious duplicates; the Knowledge Agent handles subtle ones.
+
+**When `sessionContext` is on, will the agent search again and get duplicate context?**
+
+The behavioral guidance adjusts when `sessionContext` is enabled. Instead of "search with memory_search when prior context would help," it tells the agent "relevant memories have already been injected — use memory_search only for specific follow-up queries." This reduces redundant searches. The injected context and manual search results are in different XML blocks, so even if overlap occurs, it doesn't confuse the agent — it just sees the same fact confirmed from two sources.
+
+**What happens to conversations I don't explicitly save?**
+
+With `sessionDigest` enabled (the default), every conversation is saved as a searchable thread — you can find it later with `nowledge_mem_thread_search`. On top of that, a lightweight LLM triage checks if the conversation contained decisions, insights, or preferences worth keeping as structured memories. If yes, they're extracted with proper types, labels, and temporal context. If the conversation was routine ("fix this typo"), nothing extra is saved.
+
+**Can memories be wrong or outdated?**
+
+Yes. Memories are what you or the AI saved at a point in time. Nowledge Mem's EVOLVES chains track how understanding changes — a newer memory can supersede, enrich, or challenge an older one. The Knowledge Agent identifies these relationships automatically. When you search, the relevance scoring considers recency, so newer memories rank higher by default.
+
 ## Slash Commands
 
 | Command | Description |
@@ -159,9 +329,12 @@ openclaw nowledge-mem status
 
 | Key | Type | Default | Description |
 |-----|------|---------|-------------|
-| `autoRecall` | boolean | `false` | Inject Working Memory + relevant memories at session start |
-| `autoCapture` | boolean | `false` | Thread capture + LLM distillation at session end |
-| `maxRecallResults` | integer | `5` | Max memories to recall at session start (only used when autoRecall is enabled) |
+| `sessionContext` | boolean | `false` | Inject Working Memory + relevant memories at prompt time |
+| `sessionDigest` | boolean | `true` | Thread capture + LLM distillation at session end |
+| `maxContextResults` | integer | `5` | Max memories to inject at prompt time (1–20, only used when sessionContext is enabled) |
+| `digestMinInterval` | integer | `300` | Minimum seconds between session digests for the same thread (0–86400) |
+| `apiUrl` | string | `""` | Remote server URL. Empty = local (`http://127.0.0.1:14242`) |
+| `apiKey` | string | `""` | API key for remote access. Injected as `NMEM_API_KEY` env var — never logged |
 
 ## What Makes This Different
 

package/openclaw.plugin.json

@@ -1,23 +1,23 @@
 {
 	"id": "openclaw-nowledge-mem",
-	"version": "0.6.2",
+	"version": "0.6.5",
 	"kind": "memory",
 	"uiHints": {
-		"autoRecall": {
-			"label": "Auto-recall at session start",
-			"help": "Inject Working Memory and relevant memories at session start. Off by default \u2014 the agent can call memory_search on demand instead."
+		"sessionContext": {
+			"label": "Session context injection",
+			"help": "Inject Working Memory and relevant memories at prompt time. Off by default — the agent can call memory_search on demand instead."
 		},
-		"autoCapture": {
-			"label": "Auto-capture at session end",
-			"help": "Capture conversation threads and distill key memories via LLM at session end"
+		"sessionDigest": {
+			"label": "Session digest at end",
+			"help": "Capture conversation threads and distill key memories via LLM at session end. On by default — negligible cost, one triage call per session."
 		},
-		"captureMinInterval": {
-			"label": "Minimum capture interval (seconds)",
-			"help": "Minimum seconds between auto-captures for the same thread. Prevents heartbeat-driven burst captures. Set to 0 for no limit."
+		"digestMinInterval": {
+			"label": "Minimum digest interval (seconds)",
+			"help": "Minimum seconds between session digests for the same thread. Prevents heartbeat-driven burst captures. Set to 0 for no limit."
 		},
-		"maxRecallResults": {
-			"label": "Max recall results",
-			"help": "How many memories to inject for each recall cycle (1\u201320)"
+		"maxContextResults": {
+			"label": "Max context results",
+			"help": "How many memories to inject for each context cycle (1–20)"
 		},
 		"apiUrl": {
 			"label": "Server URL (remote mode)",
@@ -25,36 +25,36 @@
 		},
 		"apiKey": {
 			"label": "API key (remote mode)",
-			"help": "Required when connecting to a remote server. Never logged or passed as a CLI argument \u2014 injected as NMEM_API_KEY env var only.",
+			"help": "Required when connecting to a remote server. Never logged or passed as a CLI argument — injected as NMEM_API_KEY env var only.",
 			"secret": true
 		}
 	},
 	"configSchema": {
 		"type": "object",
 		"properties": {
-			"autoRecall": {
+			"sessionContext": {
 				"type": "boolean",
 				"default": false,
-				"description": "Inject Working Memory and recalled memories at session start. Off by default \u2014 the agent queries memory on demand via tools."
+				"description": "Inject Working Memory and recalled memories at prompt time. Off by default — the agent queries memory on demand via tools."
 			},
-			"autoCapture": {
+			"sessionDigest": {
 				"type": "boolean",
-				"default": false,
-				"description": "Capture conversation threads and distill key memories via LLM at session end"
+				"default": true,
+				"description": "Capture conversation threads and distill key memories via LLM at session end. On by default."
 			},
-			"captureMinInterval": {
+			"digestMinInterval": {
 				"type": "integer",
 				"default": 300,
 				"minimum": 0,
 				"maximum": 86400,
-				"description": "Minimum seconds between auto-captures for the same thread (0 = no limit). Prevents heartbeat-driven burst captures."
+				"description": "Minimum seconds between session digests for the same thread (0 = no limit). Prevents heartbeat-driven burst captures."
 			},
-			"maxRecallResults": {
+			"maxContextResults": {
 				"type": "integer",
 				"default": 5,
 				"minimum": 1,
 				"maximum": 20,
-				"description": "Maximum memories to recall at session start (only used when autoRecall is enabled)"
+				"description": "Maximum memories to inject at prompt time (only used when sessionContext is enabled)"
 			},
 			"apiUrl": {
 				"type": "string",
@@ -64,7 +64,7 @@
 			"apiKey": {
 				"type": "string",
 				"default": "",
-				"description": "API key for remote access. Stored in plugin config, injected as NMEM_API_KEY env var \u2014 never logged."
+				"description": "API key for remote access. Stored in plugin config, injected as NMEM_API_KEY env var — never logged."
 			}
 		},
 		"additionalProperties": false

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nowledge/openclaw-nowledge-mem",
-	"version": "0.6.2",
+	"version": "0.6.5",
 	"type": "module",
 	"description": "Nowledge Mem memory plugin for OpenClaw, local-first personal knowledge base",
 	"author": {

package/src/client.js

@@ -359,6 +359,13 @@ export class NowledgeMemClient {
 			eventStart: m.event_start ?? null,
 			eventEnd: m.event_end ?? null,
 			temporalContext: m.temporal_context ?? null,
+			// Thread provenance: links memory to the conversation it was distilled from.
+			// CLI returns `source_thread`, API metadata returns `source_thread_id`.
+			sourceThreadId:
+				m.source_thread ??
+				m.source_thread_id ??
+				m.metadata?.source_thread_id ??
+				null,
 		};
 	}
 
@@ -722,6 +729,181 @@ export class NowledgeMemClient {
 		);
 	}
 
+	// ── Thread search ────────────────────────────────────────────────────────
+
+	/**
+	 * Search conversation threads by keyword. Uses BM25 full-text search
+	 * across all stored messages.
+	 *
+	 * @param {string} query  Search keywords
+	 * @param {number} [limit=3]  Max threads to return
+	 * @returns {Promise<{ threads: Array, totalFound: number }>}
+	 */
+	async searchThreads(query, limit = 3) {
+		const normalizedLimit = Math.min(
+			20,
+			Math.max(1, Math.trunc(Number(limit) || 3)),
+		);
+		const qs = new URLSearchParams({
+			query: String(query || ""),
+			mode: "full",
+			limit: String(normalizedLimit),
+		});
+		try {
+			const data = await this.apiJson(
+				"GET",
+				`/threads/search?${qs.toString()}`,
+			);
+			return {
+				threads: data.threads ?? [],
+				totalFound: Number(data.total_found ?? 0),
+			};
+		} catch (err) {
+			// Thread search is best-effort — don't fail the whole operation
+			this.logger.warn?.(
+				`searchThreads failed: ${err instanceof Error ? err.message : String(err)}`,
+			);
+			return { threads: [], totalFound: 0 };
+		}
+	}
+
+	/**
+	 * Full-featured thread search — used by nowledge_mem_thread_search tool.
+	 * Unlike searchThreads() (best-effort, swallows errors), this throws on failure
+	 * and supports additional parameters.
+	 *
+	 * Uses CLI: `nmem --json t search "<query>" --limit N`
+	 * Falls back to API: GET /threads/search
+	 *
+	 * @param {string} query  Search keywords
+	 * @param {{ limit?: number; source?: string }} [options]
+	 * @returns {Promise<{ threads: Array, totalFound: number }>}
+	 */
+	async searchThreadsFull(query, { limit = 10, source } = {}) {
+		const normalizedLimit = Math.min(
+			50,
+			Math.max(1, Math.trunc(Number(limit) || 10)),
+		);
+		const args = [
+			"--json",
+			"t",
+			"search",
+			String(query || ""),
+			"--limit",
+			String(normalizedLimit),
+		];
+		if (source) args.push("--source", String(source));
+
+		try {
+			const data = this.execJson(args);
+			return {
+				threads: data.threads ?? [],
+				totalFound: Number(data.total_found ?? data.total ?? 0),
+			};
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			const needsFallback =
+				message.includes("unrecognized arguments") ||
+				message.includes("invalid choice") ||
+				message.includes("argument command: invalid choice");
+			if (!needsFallback) throw err;
+
+			this.logger.warn("searchThreadsFull: CLI too old, falling back to API");
+			const qs = new URLSearchParams({
+				query: String(query || ""),
+				mode: "full",
+				limit: String(normalizedLimit),
+			});
+			if (source) qs.set("source", String(source));
+			const data = await this.apiJson(
+				"GET",
+				`/threads/search?${qs.toString()}`,
+			);
+			return {
+				threads: data.threads ?? [],
+				totalFound: Number(data.total_found ?? 0),
+			};
+		}
+	}
+
+	/**
+	 * Fetch full messages from a specific thread.
+	 * Supports pagination for progressive retrieval of long conversations.
+	 *
+	 * Uses CLI: `nmem --json t show <id> --limit N --offset O`
+	 * Falls back to API: GET /threads/{id}
+	 *
+	 * @param {string} threadId  Thread ID
+	 * @param {{ offset?: number; limit?: number }} [options]
+	 */
+	async fetchThread(threadId, { offset = 0, limit = 50 } = {}) {
+		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)),
+		);
+		const normalizedOffset = Math.max(0, Math.trunc(Number(offset) || 0));
+
+		const args = [
+			"--json",
+			"t",
+			"show",
+			id,
+			"--limit",
+			String(normalizedLimit),
+		];
+		if (normalizedOffset > 0) {
+			args.push("--offset", String(normalizedOffset));
+		}
+
+		try {
+			const data = this.execJson(args);
+			return {
+				threadId: data.thread_id ?? data.id ?? id,
+				title: data.title ?? "(untitled)",
+				source: data.source ?? "unknown",
+				messageCount: Number(data.message_count ?? data.total_messages ?? 0),
+				messages: (data.messages ?? []).map((msg) => ({
+					role: String(msg.role ?? "unknown"),
+					content: String(msg.content ?? ""),
+					timestamp: msg.timestamp ?? msg.created_at ?? null,
+				})),
+			};
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			const needsFallback =
+				message.includes("unrecognized arguments") ||
+				message.includes("invalid choice") ||
+				message.includes("argument command: invalid choice");
+			if (!needsFallback) throw err;
+
+			this.logger.warn("fetchThread: CLI too old, falling back to API");
+			const qs = new URLSearchParams({
+				limit: String(normalizedLimit),
+			});
+			if (normalizedOffset > 0) {
+				qs.set("offset", String(normalizedOffset));
+			}
+			const data = await this.apiJson(
+				"GET",
+				`/threads/${encodeURIComponent(id)}?${qs.toString()}`,
+			);
+			return {
+				threadId: data.thread_id ?? data.id ?? id,
+				title: data.title ?? "(untitled)",
+				source: data.source ?? "unknown",
+				messageCount: Number(data.message_count ?? data.total_messages ?? 0),
+				messages: (data.messages ?? []).map((msg) => ({
+					role: String(msg.role ?? "unknown"),
+					content: String(msg.content ?? ""),
+					timestamp: msg.timestamp ?? msg.created_at ?? null,
+				})),
+			};
+		}
+	}
+
 	async checkHealth() {
 		try {
 			this.exec(["status"]);

package/src/config.js

@@ -9,22 +9,42 @@ export function isDefaultApiUrl(url) {
 	return !trimmed || trimmed === API_DEFAULT_URL;
 }
 
+// Canonical config keys (new names).
 const ALLOWED_KEYS = new Set([
-	"autoRecall",
-	"autoCapture",
-	"captureMinInterval",
-	"maxRecallResults",
+	"sessionContext",
+	"sessionDigest",
+	"digestMinInterval",
+	"maxContextResults",
 	"apiUrl",
 	"apiKey",
 ]);
 
+// 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",
+};
+
 export function parseConfig(raw) {
 	const obj = raw && typeof raw === "object" ? raw : {};
 
+	// Resolve aliases: copy old-name values to new-name slots
+	// (new name takes precedence if both are present).
+	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];
+		}
+	}
+
 	// 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));
+	const unknownKeys = Object.keys(resolved).filter((k) => !ALLOWED_KEYS.has(k));
 	if (unknownKeys.length > 0) {
 		throw new Error(
 			`nowledge-mem: unknown config key${unknownKeys.length > 1 ? "s" : ""}: ${unknownKeys.join(", ")}. ` +
@@ -34,30 +54,36 @@ export function parseConfig(raw) {
 
 	// apiUrl: config wins, then env var, then local default
 	const apiUrl =
-		(typeof obj.apiUrl === "string" && obj.apiUrl.trim()) ||
+		(typeof resolved.apiUrl === "string" && resolved.apiUrl.trim()) ||
 		(typeof process.env.NMEM_API_URL === "string" &&
 			process.env.NMEM_API_URL.trim()) ||
 		"";
 
 	// apiKey: config wins, then env var — never logged, never in CLI args
 	const apiKey =
-		(typeof obj.apiKey === "string" && obj.apiKey.trim()) ||
+		(typeof resolved.apiKey === "string" && resolved.apiKey.trim()) ||
 		(typeof process.env.NMEM_API_KEY === "string" &&
 			process.env.NMEM_API_KEY.trim()) ||
 		"";
 
 	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)))
+		sessionContext:
+			typeof resolved.sessionContext === "boolean"
+				? resolved.sessionContext
+				: false,
+		sessionDigest:
+			typeof resolved.sessionDigest === "boolean"
+				? resolved.sessionDigest
+				: true,
+		digestMinInterval:
+			typeof resolved.digestMinInterval === "number" &&
+			Number.isFinite(resolved.digestMinInterval)
+				? Math.min(86400, Math.max(0, Math.trunc(resolved.digestMinInterval)))
 				: 300,
-		maxRecallResults:
-			typeof obj.maxRecallResults === "number" &&
-			Number.isFinite(obj.maxRecallResults)
-				? Math.min(20, Math.max(1, Math.trunc(obj.maxRecallResults)))
+		maxContextResults:
+			typeof resolved.maxContextResults === "number" &&
+			Number.isFinite(resolved.maxContextResults)
+				? Math.min(20, Math.max(1, Math.trunc(resolved.maxContextResults)))
 				: 5,
 		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;
@@ -293,7 +293,7 @@ export function buildAgentEndCaptureHandler(client, cfg, logger) {
 		// 2. Triage + distill: language-agnostic LLM-based capture.
 		//    Defensive guard — registration in index.js already gates on autoCapture,
 		//    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 {
@@ -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);

package/src/tools/thread-fetch.js

@@ -0,0 +1,106 @@
+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 " +
+			"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.",
+		parameters: {
+			type: "object",
+			properties: {
+				threadId: {
+					type: "string",
+					description:
+						"Thread ID from nowledge_mem_thread_search, or sourceThreadId from memory_search / memory_get results",
+				},
+				offset: {
+					type: "number",
+					description: "Skip first N messages (for pagination, default 0)",
+				},
+				limit: {
+					type: "number",
+					description: "Max messages to return (1-200, default 50)",
+				},
+			},
+			required: ["threadId"],
+		},
+		async execute(_toolCallId, params) {
+			const safeParams = params && typeof params === "object" ? params : {};
+			const threadId = String(safeParams.threadId ?? "").trim();
+			const offset = Math.max(
+				0,
+				Math.trunc(Number(safeParams.offset ?? 0) || 0),
+			);
+			const limit = Math.min(
+				200,
+				Math.max(1, Math.trunc(Number(safeParams.limit ?? 50) || 50)),
+			);
+
+			if (!threadId) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: JSON.stringify({
+								threadId: "",
+								error: "threadId is required",
+							}),
+						},
+					],
+				};
+			}
+
+			try {
+				const thread = await client.fetchThread(threadId, {
+					offset,
+					limit,
+				});
+
+				const hasMore =
+					thread.messageCount > 0 &&
+					offset + thread.messages.length < thread.messageCount;
+
+				const result = {
+					threadId: thread.threadId,
+					title: thread.title,
+					source: thread.source,
+					totalMessages: thread.messageCount,
+					offset,
+					limit,
+					returnedMessages: thread.messages.length,
+					hasMore,
+					messages: thread.messages,
+				};
+
+				return {
+					content: [
+						{
+							type: "text",
+							text: JSON.stringify(result, null, 2),
+						},
+					],
+					details: {
+						threadId: thread.threadId,
+						messageCount: thread.messages.length,
+					},
+				};
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err);
+				logger.error(`nowledge_mem_thread_fetch failed: ${message}`);
+				return {
+					content: [
+						{
+							type: "text",
+							text: JSON.stringify({
+								threadId,
+								error: message,
+							}),
+						},
+					],
+				};
+			}
+		},
+	};
+}

package/src/tools/thread-search.js

@@ -0,0 +1,108 @@
+function truncateSnippet(text, maxChars = 400) {
+	const value = String(text || "").trim();
+	if (!value) return "";
+	if (value.length <= maxChars) return value;
+	return `${value.slice(0, maxChars)}…`;
+}
+
+export function createThreadSearchTool(client, logger) {
+	return {
+		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 " +
+			"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.",
+		parameters: {
+			type: "object",
+			properties: {
+				query: {
+					type: "string",
+					description: "Search keywords or natural language query",
+				},
+				limit: {
+					type: "number",
+					description: "Max threads to return (1-20, default 5)",
+				},
+				source: {
+					type: "string",
+					description:
+						"Filter by source platform (e.g. 'openclaw', 'claude-code'). Omit to search all sources.",
+				},
+			},
+			required: ["query"],
+		},
+		async execute(_toolCallId, params) {
+			const safeParams = params && typeof params === "object" ? params : {};
+			const query = String(safeParams.query ?? "").trim();
+			const limit = Math.min(
+				20,
+				Math.max(1, Math.trunc(Number(safeParams.limit ?? 5) || 5)),
+			);
+			const rawSource = safeParams.source
+				? String(safeParams.source).trim()
+				: "";
+			const source = rawSource || undefined;
+
+			if (!query) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: JSON.stringify({ threads: [], totalFound: 0 }),
+						},
+					],
+				};
+			}
+
+			try {
+				const { threads, totalFound } = await client.searchThreadsFull(query, {
+					limit,
+					source,
+				});
+
+				const results = threads.map((t) => {
+					const msgs = (t.matched_messages ?? []).slice(0, 3);
+					return {
+						threadId: t.thread_id ?? t.id,
+						title: t.title || "(untitled thread)",
+						source: t.source ?? "unknown",
+						messageCount: Number(t.message_count ?? 0),
+						lastActivity: t.last_activity ?? null,
+						relevanceScore: Number(t.relevance_score ?? 0),
+						matchedMessages: msgs.map((m) => ({
+							role: m.role,
+							snippet: truncateSnippet(m.snippet),
+						})),
+					};
+				});
+
+				return {
+					content: [
+						{
+							type: "text",
+							text: JSON.stringify({ threads: results, totalFound }, null, 2),
+						},
+					],
+					details: { query, threadCount: results.length },
+				};
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err);
+				logger.error(`nowledge_mem_thread_search failed: ${message}`);
+				return {
+					content: [
+						{
+							type: "text",
+							text: JSON.stringify({
+								threads: [],
+								totalFound: 0,
+								error: message,
+							}),
+						},
+					],
+				};
+			}
+		},
+	};
+}