Update doc

Author: serge-p7v

agents/agents-features/agents-features-longterm-memory/Module.md

@@ -19,9 +19,9 @@ The agents-features-longterm-memory module adds long-term memory capabilities to
 | [`LongTermMemory`](src/commonMain/kotlin/ai/koog/agents/longtermmemory/feature/LongTermMemory.kt)                              | Agent feature with DSL config for retrieval & ingestion                |
 | [`SearchStorage`](../../../../../../rag/rag-base/src/commonMain/kotlin/ai/koog/rag/base/storage/SearchStorage.kt)              | Interface for searching memory records (defined in `rag-base`)         |
 | [`WriteStorage`](../../../../../../rag/rag-base/src/commonMain/kotlin/ai/koog/rag/base/storage/WriteStorage.kt)                | Interface for adding memory records (defined in `rag-base`)            |
-| [`SearchStrategy`](src/commonMain/kotlin/ai/koog/agents/longtermmemory/retrieval/SearchStrategy.kt)                            | Converts user query into a `SearchRequest`; `SimilaritySearchStrategy` is the default implementation |
-| [`SearchQueryProvider`](src/commonMain/kotlin/ai/koog/agents/longtermmemory/retrieval/SearchQueryProvider.kt)                  | Provides the search query string from a `Prompt` for retrieval         |
-| [`LastUserMessageQueryProvider`](src/commonMain/kotlin/ai/koog/agents/longtermmemory/retrieval/LastUserMessageQueryProvider.kt) | Default `SearchQueryProvider` that uses the last user message content  |
+| [`SearchStrategy`](src/commonMain/kotlin/ai/koog/agents/longtermmemory/retrieval/search/SearchStrategy.kt)                            | Converts user query into a `SearchRequest`; `SimilaritySearchStrategy` is the default implementation |
+| [`SearchQueryProvider`](src/commonMain/kotlin/ai/koog/agents/longtermmemory/retrieval/search/SearchQueryProvider.kt)                  | Provides the search query string from a `Prompt` for retrieval         |
+| [`LastUserMessageQueryProvider`](src/commonMain/kotlin/ai/koog/agents/longtermmemory/retrieval/search/LastUserMessageQueryProvider.kt) | Default `SearchQueryProvider` that uses the last user message content  |
 | [`DocumentExtractor`](src/commonMain/kotlin/ai/koog/agents/longtermmemory/ingestion/extraction/DocumentExtractor.kt)           | Transforms messages into `TextDocument`s for storage                   |
 | [`MessagePassingDocumentExtractor`](src/commonMain/kotlin/ai/koog/agents/longtermmemory/ingestion/extraction/MessagePassingDocumentExtractor.kt) | Default `DocumentExtractor`; filters messages by role (`User`/`Assistant` by default) |
 | [`PromptAugmenter`](src/commonMain/kotlin/ai/koog/agents/longtermmemory/retrieval/augmentation/PromptAugmenter.kt)             | Interface for augmenting prompts with relevant context                 |

agents/agents-features/agents-features-longterm-memory/src/commonMain/kotlin/ai/koog/agents/longtermmemory/ingestion/extraction/DocumentExtractor.kt

@@ -10,7 +10,7 @@ import kotlin.jvm.JvmStatic
  * This is a functional interface (SAM) that defines how a list of messages
  * should be transformed into a list of [TextDocument]s for storage.
  * It provides flexibility in how messages are filtered, transformed, and
- * converted into memory records while maintaining type safety.
+ * converted into [TextDocument]s while maintaining type safety.
  *
  * Pre-built implementations are available for common ingestion patterns:
  * - [MessagePassingDocumentExtractor] - Filters messages by role
@@ -33,7 +33,7 @@ import kotlin.jvm.JvmStatic
  * val customExtractor = DocumentExtractor { messages ->
  *     messages
  *         .filter { it.role == Message.Role.Assistant }
- *         .map { MemoryRecord(content = summarize(it.content)) }
+ *         .map { MemoryRecord(content = it.content) }
  * }
  * ```
  *
@@ -42,16 +42,16 @@ import kotlin.jvm.JvmStatic
  * DocumentExtractor customExtractor = (messages) ->
  *     messages.stream()
  *         .filter(m -> m.getRole() == Message.Role.Assistant)
- *         .map(m -> new MemoryRecord(m.getContent()))
+ *         .map(m -> new MemoryRecord(m.getContent(), null, Collections.emptyMap()))
  *         .collect(Collectors.toList());
  * ```
  */
 public fun interface DocumentExtractor {
     /**
-     * Transforms a list of messages into a list of memory records for storage.
+     * Transforms a list of messages into a list of [TextDocument]s for storage.
      *
-     * @param messages The messages to transform into memory records
-     * @return List of memory records to be stored
+     * @param messages The messages to transform into [TextDocument]s
+     * @return List of [TextDocument]s to be stored
      */
     public suspend fun extract(messages: List<Message>): List<TextDocument>
 

agents/agents-features/agents-features-longterm-memory/src/commonMain/kotlin/ai/koog/agents/longtermmemory/ingestion/extraction/MessagePassingDocumentExtractor.kt

@@ -8,7 +8,7 @@ import ai.koog.rag.base.TextDocument
  * Default extractor that filters messages by role.
  *
  * This extractor filters messages to only include those with roles in
- * [messageRolesToExtract], then converts each message's content into [MemoryRecord]s.
+ * [messageRolesToExtract], then converts each message's content into [TextDocument]s.
  *
  * @property messageRolesToExtract The set of message roles to extract and persist.
  *   Defaults to `setOf(Message.Role.User, Message.Role.Assistant)`.
@@ -37,7 +37,7 @@ public class MessagePassingDocumentExtractor(
      */
     public class Builder {
         /**
-         * The set of message roles to provide. Defaults to User and Assistant.
+         * The set of message roles to extract. Defaults to User and Assistant.
          */
         public var extractRoles: Set<Message.Role> = setOf(Message.Role.User, Message.Role.Assistant)
 

agents/agents-features/agents-features-longterm-memory/src/commonMain/kotlin/ai/koog/agents/longtermmemory/retrieval/RetrievalSettings.kt

@@ -15,7 +15,7 @@ import ai.koog.rag.base.storage.search.SearchRequest
  * Settings controlling how memory records are retrieved and injected into prompts (RAG).
  *
  * @param storage The retrieval storage to search for relevant memory records.
- * @param searchQueryProvider The extractor that defines how to derive the search query from the prompt.
+ * @param searchQueryProvider The provider that defines how to derive the search query from the prompt.
  *   Defaults to [ai.koog.agents.longtermmemory.retrieval.search.LastUserMessageQueryProvider], which uses the last user message content.
  * @param searchStrategy The strategy that defines how to search the retrieval store.
  * @param promptAugmenter The augmenter that defines how retrieved context is inserted into the prompt.

agents/agents-features/agents-features-longterm-memory/src/commonMain/kotlin/ai/koog/agents/longtermmemory/retrieval/augmentation/SystemPromptAugmenter.kt

@@ -9,8 +9,7 @@ import ai.koog.rag.base.storage.search.SearchResult
 /**
  * A [PromptAugmenter] that inserts retrieved context as a system message at the beginning of the prompt.
  *
- * If an existing system message is present, the new context system message is inserted
- * before it, keeping each system message focused on a single concern.
+ * The new context system message is prepended before all existing messages.
  * If there is no system message in the prompt, the prompt is returned unchanged.
  *
  * @param template The template for the system message. Use [PromptAugmenter.RELEVANT_CONTEXT_PLACEHOLDER] placeholder.

agents/agents-features/agents-features-longterm-memory/src/commonMain/kotlin/ai/koog/agents/longtermmemory/retrieval/search/SearchStrategy.kt

@@ -8,7 +8,7 @@ import kotlin.jvm.JvmStatic
  * Search strategy for creating search requests during prompt augmentation.
  *
  * This is a functional interface (SAM) that defines how a user query string
- * should be transformed into a [SimilaritySearchRequest] for storage.
+ * should be transformed into a [SearchRequest] for retrieval.
  *
  * **[SimilaritySearchStrategy] is the default implementation.**
  * It uses vector embeddings for semantic search and works with all supported vector backends.
@@ -33,10 +33,10 @@ import kotlin.jvm.JvmStatic
  */
 public fun interface SearchStrategy {
     /**
-     * Maps a query string into a [SearchRequest] for the storage.
+     * Maps a query string into a [SearchRequest] for retrieval.
      *
      * @param query The user's query string (typically the last user message content)
-     * @return The similarity search request to be executed
+     * @return The search request to be executed
      */
     public fun create(query: String): SearchRequest
 

agents/agents-features/agents-features-longterm-memory/src/commonMain/kotlin/ai/koog/agents/longtermmemory/storage/InMemoryRecordStorage.kt

@@ -18,8 +18,8 @@ import kotlin.uuid.ExperimentalUuidApi
 import kotlin.uuid.Uuid
 
 /**
- * In-memory implementation of [SearchStorage]
- * and [WriteStorage] that stores records in a map.
+ * In-memory implementation of [SearchStorage], [WriteStorage], [LookupStorage],
+ * and [DeletionStorage] that stores records in a map.
  *
  * This implementation is useful for testing, development, and scenarios where persistence
  * is not required. All data is stored in memory and will be lost when the application stops.

docs/docs/features/long-term-memory.md

@@ -175,7 +175,7 @@ Ingestion runs once when the agent run completes: the final accumulated session
 
 ## Disabling Automatic Behavior
 
-By default, retrieval and ingestion run automatically (before and after LLM calls, respectively). You can disable automatic behavior while still having access to the configured storage and strategies from within strategy nodes:
+By default, retrieval and ingestion run automatically (retrieval runs before each LLM call; ingestion runs once when the agent completes). You can disable automatic behavior while still having access to the configured storage and strategies from within strategy nodes:
 
 === "Kotlin"