Skip to main content

Class: MemorySearchTool

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

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:159

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:122

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:116

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:113

Human-readable display name.

Implementation of​

ITool.displayName

hasSideEffects​

readonly hasSideEffects: false = false

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

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:107

Globally unique tool identifier.

Implementation of​

ITool.id

inputSchema​

readonly inputSchema: JSONSchemaObject

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

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:110

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:189

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 fts
JOIN memory_traces mt ON mt.rowid = fts.rowid
WHERE fts.memory_traces_fts MATCH ?
  AND mt.deleted = 0
  [AND mt.type = ?]    -- when type filter provided
  [AND mt.scope = ?]   -- when scope filter provided
ORDER BY rank          -- FTS5 BM25 relevance (lower = more relevant)
LIMIT ?

Tags are stored as JSON arrays; they are parsed and returned as string[]. Malformed tag JSON returns an empty array rather than throwing.

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