From cef675233b12384d3db0cfd253ba29f2098c0074 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sun, 2 Aug 2026 17:06:32 -0700 Subject: [PATCH] docs(memory): explain overlapping hook and transcript indexing (#118299) --- docs/automation/hooks.md | 12 ++++++++++++ docs/reference/memory-config.md | 12 ++++++++++++ 2 files changed, 24 insertions(+) diff --git a/docs/automation/hooks.md b/docs/automation/hooks.md index d5e0d40bc913..d0087d8c4f33 100644 --- a/docs/automation/hooks.md +++ b/docs/automation/hooks.md @@ -245,6 +245,18 @@ openclaw hooks enable On `/new`, `/reset`, daily reset, or idle expiry, extracts the last user/assistant messages (default 15, configurable with `hooks.internal.entries.session-memory.messages`) and saves them to `/memory/YYYY-MM-DD-HHMM.md` using `agents.defaults.userTimezone`. When no user timezone is configured, it falls back to the host timezone. Memory capture runs in the background so reset handling and replacement sessions are not delayed by transcript reads or optional slug generation. Set `hooks.internal.entries.session-memory.llmSlug: true` to generate descriptive filename slugs, and optionally set `hooks.internal.entries.session-memory.model` to a configured alias such as `sonnet`, a bare model ID on the agent's default provider, or a `provider/model` ref. Slug generation uses the agent's default model when `model` is omitted and falls back to timestamp slugs when unavailable. Requires `workspace.dir` to be configured. + +The `memory` source already indexes this hook's saved conversation excerpts. If +[session transcript indexing](/reference/memory-config#session-memory-search) +is also enabled, the same conversation can appear from both `memory` and +`sessions`, producing overlapping search results and additional embedding work. +For hook-only recall, set `memory.search.sources: ["memory"]` and +`memory.search.rememberAcrossConversations: false`; `sources` alone does not +prevent cross-conversation recall from adding `sessions`. For full-transcript +recall instead, run `openclaw hooks disable session-memory`. Enable both only +when you intentionally want both representations. + + ### bootstrap-extra-files config diff --git a/docs/reference/memory-config.md b/docs/reference/memory-config.md index 66c227e52143..74570d44ee91 100644 --- a/docs/reference/memory-config.md +++ b/docs/reference/memory-config.md @@ -465,6 +465,18 @@ Index session transcripts and surface them via `memory_search`: Session indexing is opt-in and runs asynchronously. Results can be slightly stale. Session logs live on disk, so treat filesystem access as the trust boundary. + +The [session-memory hook](/automation/hooks#session-memory) saves conversation +excerpts to `/memory/`, which the `memory` source already indexes. +If transcript indexing is also enabled, the same conversation can appear from +both `memory` and `sessions`, resulting in overlapping search results and +additional embedding work. For hook-only recall, set `sources: ["memory"]` and +`rememberAcrossConversations: false`; `sources` alone is insufficient because +cross-conversation recall automatically adds `sessions`. For full-transcript +recall instead, run `openclaw hooks disable session-memory`. Enable both only +when you intentionally want both representations. + + Ordinary model-invoked session transcript search obeys [`tools.sessions.visibility`](/gateway/config-tools#toolssessions). The default `tree` visibility exposes the current session, sessions it spawned, and