Skip to main content

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​

Brain

The agent's shared SQLite brain database connection.

Returns​

MemorySearchTool

Properties​

category​

readonly category: "memory" = 'memory'

Defined in: packages/agentos/src/cognition/memory/io/tools/MemorySearchTool.ts:135

Logical category for discovery and grouping.

Implementation of​

ITool.category


description​

readonly description: string

Defined in: packages/agentos/src/cognition/memory/io/tools/MemorySearchTool.ts:129

LLM-facing description.

Implementation of​

ITool.description


displayName​

readonly displayName: "Search Memory" = 'Search Memory'

Defined in: packages/agentos/src/cognition/memory/io/tools/MemorySearchTool.ts:126

Human-readable display name.

Implementation of​

ITool.displayName


hasSideEffects​

readonly hasSideEffects: 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​

ITool.hasSideEffects


id​

readonly id: "memory-search-v1" = 'memory-search-v1'

Defined in: packages/agentos/src/cognition/memory/io/tools/MemorySearchTool.ts:120

Globally unique tool identifier.

Implementation of​

ITool.id


inputSchema​

readonly inputSchema: 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​

ITool.inputSchema


name​

readonly name: "memory_search" = 'memory_search'

Defined in: packages/agentos/src/cognition/memory/io/tools/MemorySearchTool.ts:123

LLM-facing tool name.

Implementation of​

ITool.name

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​

ToolExecutionContext

Tool execution context used to resolve scoped searches.

Returns​

Promise<ToolExecutionResult<MemorySearchOutput>>

{ results } array on success, or an error result.

Implementation of​

ITool.execute