Skip to main content

Class: MemoryAddTool

Defined in: packages/agentos/src/cognition/memory/io/tools/MemoryAddTool.ts:77

ITool implementation that stores a new memory trace in the agent's SQLite brain database.

Usage:

const tool = new MemoryAddTool(brain);
const result = await tool.execute(
  { content: 'User prefers dark mode.', tags: ['preference', 'ui'] },
  context,
);
// result.output.traceId → 'mt_1711234567890_0'

Implements​

  • ITool<MemoryAddInput, MemoryAddOutput>

Constructors​

Constructor​

new MemoryAddTool(brain): MemoryAddTool

Defined in: packages/agentos/src/cognition/memory/io/tools/MemoryAddTool.ts:136

Parameters​

brain​

Brain

The agent's shared SQLite brain database connection.

Returns​

MemoryAddTool

Properties​

category​

readonly category: "memory" = 'memory'

Defined in: packages/agentos/src/cognition/memory/io/tools/MemoryAddTool.ts:95

Logical category for discovery and grouping.

Implementation of​

ITool.category

description​

readonly description: "Store a new memory trace. The agent calls this to remember important facts, decisions, or observations." = 'Store a new memory trace. The agent calls this to remember important facts, decisions, or observations.'

Defined in: packages/agentos/src/cognition/memory/io/tools/MemoryAddTool.ts:91

Description shown to the LLM when deciding which tool to invoke. Must be comprehensive enough for the model to understand when to call this.

Implementation of​

ITool.description

displayName​

readonly displayName: "Add Memory" = 'Add Memory'

Defined in: packages/agentos/src/cognition/memory/io/tools/MemoryAddTool.ts:85

Human-readable display name for UIs and logs.

Implementation of​

ITool.displayName

hasSideEffects​

readonly hasSideEffects: true = true

Defined in: packages/agentos/src/cognition/memory/io/tools/MemoryAddTool.ts:101

This tool writes to the database. Callers may request confirmation before execution when hasSideEffects = true.

Implementation of​

ITool.hasSideEffects

id​

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

Defined in: packages/agentos/src/cognition/memory/io/tools/MemoryAddTool.ts:79

Globally unique tool identifier.

Implementation of​

ITool.id

inputSchema​

readonly inputSchema: JSONSchemaObject

Defined in: packages/agentos/src/cognition/memory/io/tools/MemoryAddTool.ts:107

JSON schema for input validation and LLM tool-call construction. All optional fields default gracefully inside execute().

Implementation of​

ITool.inputSchema

name​

readonly name: "memory_add" = 'memory_add'

Defined in: packages/agentos/src/cognition/memory/io/tools/MemoryAddTool.ts:82

LLM-facing tool name (snake_case, as the LLM will call it).

Implementation of​

ITool.name

Methods​

execute()​

execute(args, context): Promise<ToolExecutionResult<MemoryAddOutput>>

Defined in: packages/agentos/src/cognition/memory/io/tools/MemoryAddTool.ts:158

Insert a new memory trace row into memory_traces.

Defaults applied when optional fields are absent:

  • type → 'episodic'
  • scope → 'user'
  • tags → []

The trace is created with strength = 1.0 (maximum encoding strength) and deleted = 0 (active). No embedding is computed here — the background EmbeddingEncoder will embed it asynchronously.

Parameters​

args​

MemoryAddInput

Memory add input (content, optional type/scope/tags).

context​

ToolExecutionContext

Tool execution context used to resolve the scope ID.

Returns​

Promise<ToolExecutionResult<MemoryAddOutput>>

{ traceId } on success, or an error result.

Implementation of​

ITool.execute