Class: MemorySearchTool
Defined in: packages/agentos/src/cognition/memory/io/tools/MemorySearchTool.ts:118
ITool implementation that searches the agent's memory traces using FTS5.
Usage:
const tool = new MemorySearchTool(brain);
const result = await tool.execute(
{ query: 'dark mode preference', scope: 'user', limit: 5 },
context,
);
// result.output.results → [{ id, content, type, scope, strength, tags }, ...]
Implements
ITool<MemorySearchInput,MemorySearchOutput>
Constructors
Constructor
new MemorySearchTool(
brain):MemorySearchTool
Defined in: packages/agentos/src/cognition/memory/io/tools/MemorySearchTool.ts:172
Parameters
brain
The agent's shared SQLite brain database connection.
Returns
MemorySearchTool
Properties
category
readonlycategory:"memory"='memory'
Defined in: packages/agentos/src/cognition/memory/io/tools/MemorySearchTool.ts:135
Logical category for discovery and grouping.
Implementation of
description
readonlydescription:string
Defined in: packages/agentos/src/cognition/memory/io/tools/MemorySearchTool.ts:129
LLM-facing description.
Implementation of
displayName
readonlydisplayName:"Search Memory"='Search Memory'
Defined in: packages/agentos/src/cognition/memory/io/tools/MemorySearchTool.ts:126
Human-readable display name.
Implementation of
hasSideEffects
readonlyhasSideEffects:false=false
Defined in: packages/agentos/src/cognition/memory/io/tools/MemorySearchTool.ts:138
This tool only reads from the database — no side effects.
Implementation of
id
readonlyid:"memory-search-v1"='memory-search-v1'
Defined in: packages/agentos/src/cognition/memory/io/tools/MemorySearchTool.ts:120
Globally unique tool identifier.
Implementation of
inputSchema
readonlyinputSchema:JSONSchemaObject
Defined in: packages/agentos/src/cognition/memory/io/tools/MemorySearchTool.ts:141
JSON schema for input validation and LLM tool-call construction.
Implementation of
name
readonlyname:"memory_search"='memory_search'
Defined in: packages/agentos/src/cognition/memory/io/tools/MemorySearchTool.ts:123
LLM-facing tool name.
Implementation of
Methods
execute()
execute(
args,context):Promise<ToolExecutionResult<MemorySearchOutput>>
Defined in: packages/agentos/src/cognition/memory/io/tools/MemorySearchTool.ts:213
Run a full-text search against memory_traces_fts and join back to
memory_traces for metadata.
The SQL pattern:
SELECT mt.id, mt.content, mt.type, mt.scope, mt.strength, mt.tags
FROM memory_traces_fts memory_traces_fts
JOIN memory_traces mt ON mt.rowid = memory_traces_fts.rowid
WHERE memory_traces_fts MATCH ?
AND mt.deleted = 0
AND mt.scope <> 'conversation' -- always: a subject's conversation memory is never searched here
[AND mt.type = ?] -- when type filter provided
[AND mt.scope = ?] -- when scope filter provided
[AND ((mt.scope = ? AND mt.scope_id = ?) OR ... OR (mt.scope_id = '' AND NOT (<metadata names a scope id>)))]
-- with the turn's scope ids
ORDER BY memory_traces_fts.rank -- FTS5 BM25 relevance (lower = more relevant);
-- FTS4 orders by length(offsets(memory_traces_fts)) DESC
LIMIT ?
Tags are stored as JSON arrays; they are parsed and returned as string[]. Malformed tag JSON returns an empty array rather than throwing.
Where a learning layer put the turn's scope ids on the call, the search reads the indexed scope_id column: the
turn's own user, persona and thread scope ids, its organization's id, and the traces filed under no scope
id (an ingested document's); a scope filter narrows that list to the scope's own ids and its unscoped traces. A
row that holds '' while its metadata names a scope id (namesScopeId) is some scope's, not unscoped: a release
older than the column writes such rows to a Brain this process holds open, and no turn reads one until the Brain's
next open files it under that id.
Parameters
args
MemorySearchInput
Search input (query, optional type/scope/limit).
context
Tool execution context used to resolve scoped searches.
Returns
Promise<ToolExecutionResult<MemorySearchOutput>>
{ results } array on success, or an error result.