@nowledge/openclaw-nowledge-mem 0.3.0 → 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,19 +1,23 @@
 {
 	"id": "openclaw-nowledge-mem",
-	"version": "0.3.0",
+	"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."
 		},
-		"maxRecallResults": {
-			"label": "Max recall results",
-			"help": "How many memories to inject for each recall cycle (1\u201320)"
+		"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."
+		},
+		"maxContextResults": {
+			"label": "Max context results",
+			"help": "How many memories to inject for each context cycle (1–20)"
 		},
 		"apiUrl": {
 			"label": "Server URL (remote mode)",
@@ -21,29 +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."
+			},
+			"digestMinInterval": {
+				"type": "integer",
+				"default": 300,
+				"minimum": 0,
+				"maximum": 86400,
+				"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",
@@ -53,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.3.0",
+	"version": "0.6.5",
 	"type": "module",
 	"description": "Nowledge Mem memory plugin for OpenClaw, local-first personal knowledge base",
 	"author": {