Memory
Tool providing agent memory search within a context.
A single agentic tool: the LLM passes a freeform natural-language query and Memory runs a hybrid retrieval — a vector-similarity probe AND a keyword (substring) probe over the same scoped propositions — then unions the hits, tagging each with the probe(s) that found it ([vector], [keyword], [vector,keyword]). Vector carries question-shaped queries; keyword adds precision for exact terms, names and phrases. There is no predicate / subject / object parameter surface — the LLM asks in natural language and, if the first query is unconvincing, simply asks again with different wording. Calling with no query lists all memories by confidence.
Fusion scoring (RRF) and graph-distance reranking are deliberately NOT implemented yet — vector hits keep similarity order, keyword-only hits follow by confidence.
The context is baked in at construction time, ensuring the LLM can only access memories within the authorized context.
The description dynamically reflects how many memories are available.
Implements LlmReference so that key memories are surfaced directly in the LLM system prompt (via contribution) rather than buried in tool metadata. This ensures the LLM can reason about known facts without needing a tool call.
Supports a two-tier retrieval strategy:
Eager: Key memories are preloaded into the system prompt via contribution, making them immediately visible to the LLM with no tool call overhead. Three eager modes are available:
withEagerSearchAbout: Preload by vector similarity search request (e.g., recent conversation)
withEagerQuery: Preload by structured query (e.g., top-N by confidence)
withEagerTopicSearch: Preload by vector similarity to the topic
On-demand: The LLM calls this tool with search parameters for specific or additional memories.
When eager memories are loaded, subsequent tool calls automatically deduplicate results so the LLM always receives new information.
Example: preload memories relevant to the current conversation:
val memory = Memory.forContext(contextId)
.withRepository(propositionRepository)
.withEagerSearchAbout(recentConversationText, 10)Example: preload by topic similarity and structured query:
val memory = Memory.forContext(contextId)
.withRepository(propositionRepository)
.withTopic("classical music preferences")
.withEagerTopicSearch(5)
.withEagerQuery { it.orderedByEffectiveConfidence().withLimit(3) }Parameters
The context to search within
The proposition repository to query
Projector for categorizing memories by knowledge type
Minimum confidence threshold for memories
Default limit for search results
Description of the memories we can retrieve. Should complete with the form "memories about
Description of when to use the memory tools.
Optional query transformer that narrows the scope of all queries. Applied on top of the base query (contextId + minConfidence) before any tool-specific additions. Use this to restrict Memory to a subset of propositions (e.g., by entity, level, or temporal range). Cannot widen the base scope, only narrow it.
Optional query transformer to eagerly load key memories into the description. When set, the description will include memories fetched using this query, making them immediately available to the LLM without requiring a tool call. Applied on top of the narrowed base query.
Optional limit for eager topic-based similarity search. When set, uses the topic to perform a vector similarity search and preloads matching memories into the description. Can be used alongside or instead of eagerQuery.
Optional similarity search request to eagerly preload memories. When set, performs a vector similarity search using this request and preloads matching memories into the description. Ideal for passing recent conversation content so the LLM sees relevant memories without needing a tool call.
Constructors
Types
Functions
Narrow the scope of all memory queries.
Set the default limit for search results.
Set an eager query to preload key memories into the description.
Enable eager topic-based similarity search.
Set the minimum confidence threshold for returned memories. Memories with effective confidence below this are filtered out.
Set the projector for categorizing memories by knowledge type.
Wire a ProvenanceResolver so every returned proposition is annotated with its source(s). Folds citation/"why do you think" answers into ordinary recall — no separate evidence tool.