Class: MemoryMergeTool
Defined in: packages/agentos/src/cognition/memory/io/tools/MemoryMergeTool.ts:116
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
new MemoryMergeTool(
brain,writeBack?):MemoryMergeTool
Defined in: packages/agentos/src/cognition/memory/io/tools/MemoryMergeTool.ts:163
Parameters
brain
The agent's shared SQLite brain database connection.
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
Properties
category
readonlycategory:"memory"='memory'
Defined in: packages/agentos/src/cognition/memory/io/tools/MemoryMergeTool.ts:133
Logical category for discovery and grouping.
Implementation of
description
readonlydescription:string
Defined in: packages/agentos/src/cognition/memory/io/tools/MemoryMergeTool.ts:127
LLM-facing description.
Implementation of
displayName
readonlydisplayName:"Merge Memories"='Merge Memories'
Defined in: packages/agentos/src/cognition/memory/io/tools/MemoryMergeTool.ts:124
Human-readable display name.
Implementation of
hasSideEffects
readonlyhasSideEffects:true=true
Defined in: packages/agentos/src/cognition/memory/io/tools/MemoryMergeTool.ts:136
This tool writes to the database.
Implementation of
id
readonlyid:"memory-merge-v1"='memory-merge-v1'
Defined in: packages/agentos/src/cognition/memory/io/tools/MemoryMergeTool.ts:118
Globally unique tool identifier.
Implementation of
inputSchema
readonlyinputSchema:JSONSchemaObject
Defined in: packages/agentos/src/cognition/memory/io/tools/MemoryMergeTool.ts:139
JSON schema for input validation and LLM tool-call construction.
Implementation of
name
readonlyname:"memory_merge"='memory_merge'
Defined in: packages/agentos/src/cognition/memory/io/tools/MemoryMergeTool.ts:121
LLM-facing tool name.
Implementation of
Methods
execute()
execute(
args,context):Promise<ToolExecutionResult<MemoryMergeOutput>>
Defined in: packages/agentos/src/cognition/memory/io/tools/MemoryMergeTool.ts:211
Merge the specified traces into one survivor.
Steps:
- Validate that at least 2 trace IDs were supplied.
- Load all matching, non-deleted traces from the database.
- Pick survivor by highest
retrieval_count; on a tie, the first oftraceIds. - Compute merged content (provided or concatenated).
- Union all tags, deduplicate.
- Update survivor: new content, cleared embedding, unioned tags.
- 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
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.
Implementation of
refusalBeforeApproval()
refusalBeforeApproval(
args,context):ToolExecutionResult<MemoryMergeOutput> |undefined
Defined in: packages/agentos/src/cognition/memory/io/tools/MemoryMergeTool.ts:183
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
The call's context.
Returns
ToolExecutionResult<MemoryMergeOutput> | undefined
The refusal, or undefined when the call may run.