Class MemorySearchTool

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

Methods

execute

Properties

id name displayName description category hasSideEffects inputSchema

Constructors

constructor

Methods

execute

  • execute(args, context): Promise<ToolExecutionResult<MemorySearchOutput>>

  • 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.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.

Properties

Readonly id

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

Globally unique tool identifier.

Readonly name

name: "memory_search" = 'memory_search'

LLM-facing tool name.

Readonly displayName

displayName: "Search Memory" = 'Search Memory'

Human-readable display name.

Readonly description

description: string = ...

LLM-facing description.

Readonly category

category: "memory" = 'memory'

Logical category for discovery and grouping.

Readonly hasSideEffects

hasSideEffects: false = false

This tool only reads from the database — no side effects.

Readonly inputSchema

inputSchema: JSONSchemaObject = ...

JSON schema for input validation and LLM tool-call construction.

Settings

Member Visibility

Theme

On This Page

constructorexecuteidnamedisplayNamedescriptioncategoryhasSideEffectsinputSchema