Class MemoryMergeTool

ITool implementation that merges multiple memory traces into one.

Usage:

const tool = new MemoryMergeTool(brain);
const result = await tool.execute(
  {
    traceIds: ['mt_1_0', 'mt_2_0', 'mt_3_0'],
    mergedContent: 'Consolidated insight from three related observations.',
  },
  context,
);
// result.output → { survivorId: 'mt_1_0', deletedIds: ['mt_2_0', 'mt_3_0'] }

Implements

  • ITool<MemoryMergeInput, MemoryMergeOutput>

Constructors

constructor

Methods

refusalBeforeApproval execute

Properties

id name displayName description category hasSideEffects inputSchema

Constructors

constructor

  • new MemoryMergeTool(brain, writeBack?): MemoryMergeTool

  • Parameters

    • brain: Brain

      The agent's shared SQLite brain database connection.

    • Optional writeBack: MemoryToolWriteBack

      The facade that made the tool (Memory.createTools()): the merged-away traces' knowledge-graph copies are deleted through it, and a merge a learning layer does not keep is taken back through it. Without it the tool restores the rows itself.

    Returns MemoryMergeTool

Methods

refusalBeforeApproval

  • refusalBeforeApproval(args, context): undefined | ToolExecutionResult<MemoryMergeOutput>

  • The refusal a merge meets whatever a human would answer, read before the tool orchestrator's approval gate (ITool.refusalBeforeApproval), so no one is asked to approve a write that cannot act: a freeze, and, with the turn's scope ids on the call, a session that records no writes. A refusal that reads the traces (other_user, conflict) is given when the call runs, and fewer than two ids are left to execute, which refuses the same call itself, in the same order.

    Parameters

    • args: Record<string, any>

      The call's arguments, before the input schema is checked.

    • context: ToolExecutionContext

      The call's context.

    Returns undefined | ToolExecutionResult<MemoryMergeOutput>

    The refusal, or undefined when the call may run.

execute

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

  • Merge the specified traces into one survivor.

    Steps:

    1. Validate that at least 2 trace IDs were supplied.
    2. Load all matching, non-deleted traces from the database.
    3. Pick survivor by highest retrieval_count; on a tie, the first of traceIds.
    4. Compute merged content (provided or concatenated).
    5. Union all tags, deduplicate.
    6. Update survivor: new content, cleared embedding, unioned tags.
    7. Soft-delete all non-survivor traces, and their knowledge-graph copies through the facade that made the tool.

    Parameters

    • args: MemoryMergeInput

      Merge input (traceIds, optional mergedContent).

    • context: ToolExecutionContext

      Tool execution context; where it carries the turn's scope ids, every trace the call names must be one the turn reaches: a live trace of the turn's own scopes that the turn's own user filed (another scope's reads as not found; one another user filed refuses the whole merge, other_user). The merge then runs through the learner session's recorder, writing each row only while it holds what was read (conflict otherwise). Only a freeze stops a merge, with a layer or without one (frozen).

    Returns Promise<ToolExecutionResult<MemoryMergeOutput>>

    { survivorId, deletedIds } on success, or an error result.

Properties

Readonly id

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

Globally unique tool identifier.

Readonly name

name: "memory_merge" = 'memory_merge'

LLM-facing tool name.

Readonly displayName

displayName: "Merge Memories" = 'Merge Memories'

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: true = true

This tool writes to the database.

Readonly inputSchema

inputSchema: JSONSchemaObject = ...

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

Settings

Member Visibility

Theme

On This Page

constructorrefusalBeforeApprovalexecuteidnamedisplayNamedescriptioncategoryhasSideEffectsinputSchema