@framers/agentos 0.1.101 → 0.1.102

package/dist/memory/tools/MemoryAddTool.d.ts

@@ -0,0 +1,98 @@
+/**
+ * @fileoverview MemoryAddTool — lets an agent store a new memory trace.
+ *
+ * The agent calls this tool to remember important facts, decisions, or
+ * observations. Each invocation inserts a fresh row into `memory_traces`
+ * with strength 1.0 (full encoding strength at creation time).
+ *
+ * ID format: `mt_<timestamp>_<counter>` — monotonically increasing within a
+ * process, collision-safe across typical agent interaction rates.
+ *
+ * @module memory/tools/MemoryAddTool
+ */
+import type { ITool, ToolExecutionResult, ToolExecutionContext, JSONSchemaObject } from '../../core/tools/ITool.js';
+import type { SqliteBrain } from '../store/SqliteBrain.js';
+/**
+ * Input arguments for {@link MemoryAddTool}.
+ *
+ * @property content - The text content of the memory to store.
+ * @property type    - Tulving memory type (episodic, semantic, procedural, prospective). Defaults to 'episodic'.
+ * @property scope   - Visibility scope (thread, user, persona, organization). Defaults to 'user'.
+ * @property tags    - Optional array of free-form tag strings for filtering.
+ */
+export interface MemoryAddInput extends Record<string, any> {
+    content: string;
+    type?: string;
+    scope?: string;
+    tags?: string[];
+}
+/**
+ * Output returned by {@link MemoryAddTool} on success.
+ *
+ * @property traceId - The unique ID of the newly stored memory trace.
+ */
+export interface MemoryAddOutput {
+    traceId: string;
+}
+/**
+ * ITool implementation that stores a new memory trace in the agent's
+ * SQLite brain database.
+ *
+ * **Usage:**
+ * ```ts
+ * 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'
+ * ```
+ */
+export declare class MemoryAddTool implements ITool<MemoryAddInput, MemoryAddOutput> {
+    private readonly brain;
+    /** Globally unique tool identifier. */
+    readonly id = "memory-add-v1";
+    /** LLM-facing tool name (snake_case, as the LLM will call it). */
+    readonly name = "memory_add";
+    /** Human-readable display name for UIs and logs. */
+    readonly displayName = "Add Memory";
+    /**
+     * Description shown to the LLM when deciding which tool to invoke.
+     * Must be comprehensive enough for the model to understand when to call this.
+     */
+    readonly description = "Store a new memory trace. The agent calls this to remember important facts, decisions, or observations.";
+    /** Logical category for discovery and grouping. */
+    readonly category = "memory";
+    /**
+     * This tool writes to the database.
+     * Callers may request confirmation before execution when `hasSideEffects = true`.
+     */
+    readonly hasSideEffects = true;
+    /**
+     * JSON schema for input validation and LLM tool-call construction.
+     * All optional fields default gracefully inside `execute()`.
+     */
+    readonly inputSchema: JSONSchemaObject;
+    /**
+     * @param brain - The agent's shared SQLite brain database connection.
+     */
+    constructor(brain: SqliteBrain);
+    /**
+     * 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.
+     *
+     * @param args    - Memory add input (content, optional type/scope/tags).
+     * @param _context - Tool execution context (not used by this tool).
+     * @returns `{ traceId }` on success, or an error result.
+     */
+    execute(args: MemoryAddInput, _context: ToolExecutionContext): Promise<ToolExecutionResult<MemoryAddOutput>>;
+}
+//# sourceMappingURL=MemoryAddTool.d.ts.map

package/dist/memory/tools/MemoryAddTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MemoryAddTool.d.ts","sourceRoot":"","sources":["../../../src/memory/tools/MemoryAddTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AACpH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAa3D;;;;;;;GAOG;AACH,MAAM,WAAW,cAAe,SAAQ,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;CACjB;AAMD;;;;;;;;;;;;;GAaG;AACH,qBAAa,aAAc,YAAW,KAAK,CAAC,cAAc,EAAE,eAAe,CAAC;IA2D9D,OAAO,CAAC,QAAQ,CAAC,KAAK;IA1DlC,uCAAuC;IACvC,QAAQ,CAAC,EAAE,mBAAmB;IAE9B,kEAAkE;IAClE,QAAQ,CAAC,IAAI,gBAAgB;IAE7B,oDAAoD;IACpD,QAAQ,CAAC,WAAW,gBAAgB;IAEpC;;;OAGG;IACH,QAAQ,CAAC,WAAW,6GACwF;IAE5G,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,YAAY;IAE7B;;;OAGG;IACH,QAAQ,CAAC,cAAc,QAAQ;IAE/B;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAwBpC;IAEF;;OAEG;gBAC0B,KAAK,EAAE,WAAW;IAM/C;;;;;;;;;;;;;;;OAeG;IACG,OAAO,CACX,IAAI,EAAE,cAAc,EACpB,QAAQ,EAAE,oBAAoB,GAC7B,OAAO,CAAC,mBAAmB,CAAC,eAAe,CAAC,CAAC;CA0BjD"}

package/dist/memory/tools/MemoryAddTool.js

@@ -0,0 +1,131 @@
+/**
+ * @fileoverview MemoryAddTool — lets an agent store a new memory trace.
+ *
+ * The agent calls this tool to remember important facts, decisions, or
+ * observations. Each invocation inserts a fresh row into `memory_traces`
+ * with strength 1.0 (full encoding strength at creation time).
+ *
+ * ID format: `mt_<timestamp>_<counter>` — monotonically increasing within a
+ * process, collision-safe across typical agent interaction rates.
+ *
+ * @module memory/tools/MemoryAddTool
+ */
+// ---------------------------------------------------------------------------
+// Counter for unique ID generation within the process lifetime
+// ---------------------------------------------------------------------------
+/** Monotonic counter shared across all MemoryAddTool instances in the process. */
+let _idCounter = 0;
+// ---------------------------------------------------------------------------
+// MemoryAddTool
+// ---------------------------------------------------------------------------
+/**
+ * ITool implementation that stores a new memory trace in the agent's
+ * SQLite brain database.
+ *
+ * **Usage:**
+ * ```ts
+ * 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'
+ * ```
+ */
+export class MemoryAddTool {
+    /**
+     * @param brain - The agent's shared SQLite brain database connection.
+     */
+    constructor(brain) {
+        this.brain = brain;
+        /** Globally unique tool identifier. */
+        this.id = 'memory-add-v1';
+        /** LLM-facing tool name (snake_case, as the LLM will call it). */
+        this.name = 'memory_add';
+        /** Human-readable display name for UIs and logs. */
+        this.displayName = 'Add Memory';
+        /**
+         * Description shown to the LLM when deciding which tool to invoke.
+         * Must be comprehensive enough for the model to understand when to call this.
+         */
+        this.description = 'Store a new memory trace. The agent calls this to remember important facts, decisions, or observations.';
+        /** Logical category for discovery and grouping. */
+        this.category = 'memory';
+        /**
+         * This tool writes to the database.
+         * Callers may request confirmation before execution when `hasSideEffects = true`.
+         */
+        this.hasSideEffects = true;
+        /**
+         * JSON schema for input validation and LLM tool-call construction.
+         * All optional fields default gracefully inside `execute()`.
+         */
+        this.inputSchema = {
+            type: 'object',
+            properties: {
+                content: {
+                    type: 'string',
+                    description: 'The text content of the memory to store.',
+                },
+                type: {
+                    type: 'string',
+                    enum: ['episodic', 'semantic', 'procedural', 'prospective'],
+                    description: 'Tulving memory type. Defaults to "episodic".',
+                },
+                scope: {
+                    type: 'string',
+                    enum: ['thread', 'user', 'persona', 'organization'],
+                    description: 'Visibility scope of the trace. Defaults to "user".',
+                },
+                tags: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Optional free-form tags for filtering and retrieval.',
+                },
+            },
+            required: ['content'],
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // execute
+    // ---------------------------------------------------------------------------
+    /**
+     * 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.
+     *
+     * @param args    - Memory add input (content, optional type/scope/tags).
+     * @param _context - Tool execution context (not used by this tool).
+     * @returns `{ traceId }` on success, or an error result.
+     */
+    async execute(args, _context) {
+        try {
+            const now = Date.now();
+            const traceId = `mt_${now}_${_idCounter++}`;
+            const type = args.type ?? 'episodic';
+            const scope = args.scope ?? 'user';
+            const tags = JSON.stringify(args.tags ?? []);
+            this.brain.db
+                .prepare(`INSERT INTO memory_traces
+             (id, type, scope, content, embedding, strength, created_at,
+              last_accessed, retrieval_count, tags, emotions, metadata, deleted)
+           VALUES (?, ?, ?, ?, NULL, 1.0, ?, NULL, 0, ?, '{}', '{}', 0)`)
+                .run(traceId, type, scope, args.content, now, tags);
+            return { success: true, output: { traceId } };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+}
+//# sourceMappingURL=MemoryAddTool.js.map

package/dist/memory/tools/MemoryAddTool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MemoryAddTool.js","sourceRoot":"","sources":["../../../src/memory/tools/MemoryAddTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,8EAA8E;AAC9E,+DAA+D;AAC/D,8EAA8E;AAE9E,kFAAkF;AAClF,IAAI,UAAU,GAAG,CAAC,CAAC;AA8BnB,8EAA8E;AAC9E,gBAAgB;AAChB,8EAA8E;AAE9E;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,aAAa;IAwDxB;;OAEG;IACH,YAA6B,KAAkB;QAAlB,UAAK,GAAL,KAAK,CAAa;QA1D/C,uCAAuC;QAC9B,OAAE,GAAG,eAAe,CAAC;QAE9B,kEAAkE;QACzD,SAAI,GAAG,YAAY,CAAC;QAE7B,oDAAoD;QAC3C,gBAAW,GAAG,YAAY,CAAC;QAEpC;;;WAGG;QACM,gBAAW,GAClB,yGAAyG,CAAC;QAE5G,mDAAmD;QAC1C,aAAQ,GAAG,QAAQ,CAAC;QAE7B;;;WAGG;QACM,mBAAc,GAAG,IAAI,CAAC;QAE/B;;;WAGG;QACM,gBAAW,GAAqB;YACvC,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,OAAO,EAAE;oBACP,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,0CAA0C;iBACxD;gBACD,IAAI,EAAE;oBACJ,IAAI,EAAE,QAAQ;oBACd,IAAI,EAAE,CAAC,UAAU,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,CAAC;oBAC3D,WAAW,EAAE,8CAA8C;iBAC5D;gBACD,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,IAAI,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,CAAC;oBACnD,WAAW,EAAE,oDAAoD;iBAClE;gBACD,IAAI,EAAE;oBACJ,IAAI,EAAE,OAAO;oBACb,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;oBACzB,WAAW,EAAE,sDAAsD;iBACpE;aACF;YACD,QAAQ,EAAE,CAAC,SAAS,CAAC;SACtB,CAAC;IAKgD,CAAC;IAEnD,8EAA8E;IAC9E,UAAU;IACV,8EAA8E;IAE9E;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CAAC,OAAO,CACX,IAAoB,EACpB,QAA8B;QAE9B,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACvB,MAAM,OAAO,GAAG,MAAM,GAAG,IAAI,UAAU,EAAE,EAAE,CAAC;YAE5C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,UAAU,CAAC;YACrC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,MAAM,CAAC;YACnC,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;YAE7C,IAAI,CAAC,KAAK,CAAC,EAAE;iBACV,OAAO,CACN;;;wEAG8D,CAC/D;iBACA,GAAG,CAAC,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;YAEtD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,EAAE,CAAC;QAChD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;aACxD,CAAC;QACJ,CAAC;IACH,CAAC;CACF"}

package/dist/memory/tools/MemoryDeleteTool.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @fileoverview MemoryDeleteTool — lets an agent soft-delete a memory trace.
+ *
+ * Deletion is always a soft-delete: the row in `memory_traces` is kept intact
+ * but its `deleted` flag is set to `1`. This preserves the audit trail and
+ * allows the consolidation engine to later log or compact the removal.
+ *
+ * The optional `reason` argument is currently captured in the tool contract
+ * but not stored in the database; it is reserved for a future `deleted_reason`
+ * column when schema migration tooling is in place.
+ *
+ * @module memory/tools/MemoryDeleteTool
+ */
+import type { ITool, ToolExecutionResult, ToolExecutionContext, JSONSchemaObject } from '../../core/tools/ITool.js';
+import type { SqliteBrain } from '../store/SqliteBrain.js';
+/**
+ * Input arguments for {@link MemoryDeleteTool}.
+ *
+ * @property traceId - ID of the trace to soft-delete.
+ * @property reason  - Optional human-readable explanation for the deletion.
+ *                     Useful for agents to self-document their pruning decisions.
+ */
+export interface MemoryDeleteInput extends Record<string, any> {
+    traceId: string;
+    reason?: string;
+}
+/**
+ * Output returned by {@link MemoryDeleteTool} on success.
+ *
+ * @property deleted - `true` if the trace was found and marked deleted.
+ *                     `false` if no active trace matched the given `traceId`.
+ */
+export interface MemoryDeleteOutput {
+    deleted: boolean;
+}
+/**
+ * ITool implementation that soft-deletes a memory trace from the agent's
+ * SQLite brain database.
+ *
+ * **Usage:**
+ * ```ts
+ * const tool = new MemoryDeleteTool(brain);
+ * const result = await tool.execute(
+ *   { traceId: 'mt_1711234567890_0', reason: 'Information is outdated.' },
+ *   context,
+ * );
+ * // result.output.deleted → true
+ * ```
+ */
+export declare class MemoryDeleteTool implements ITool<MemoryDeleteInput, MemoryDeleteOutput> {
+    private readonly brain;
+    /** Globally unique tool identifier. */
+    readonly id = "memory-delete-v1";
+    /** LLM-facing tool name. */
+    readonly name = "memory_delete";
+    /** Human-readable display name. */
+    readonly displayName = "Delete Memory";
+    /** LLM-facing description. */
+    readonly description: string;
+    /** Logical category for discovery and grouping. */
+    readonly category = "memory";
+    /** This tool writes to the database. */
+    readonly hasSideEffects = true;
+    /** JSON schema for input validation and LLM tool-call construction. */
+    readonly inputSchema: JSONSchemaObject;
+    /**
+     * @param brain - The agent's shared SQLite brain database connection.
+     */
+    constructor(brain: SqliteBrain);
+    /**
+     * Set `deleted = 1` on the memory trace matching `traceId`.
+     *
+     * The WHERE clause filters to `deleted = 0` so that attempting to
+     * delete an already-deleted trace returns `{ deleted: false }` rather
+     * than silently succeeding — this gives callers accurate feedback.
+     *
+     * @param args     - Delete input (traceId, optional reason).
+     * @param _context - Tool execution context (not used by this tool).
+     * @returns `{ deleted }` status, or an error result.
+     */
+    execute(args: MemoryDeleteInput, _context: ToolExecutionContext): Promise<ToolExecutionResult<MemoryDeleteOutput>>;
+}
+//# sourceMappingURL=MemoryDeleteTool.d.ts.map

package/dist/memory/tools/MemoryDeleteTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MemoryDeleteTool.d.ts","sourceRoot":"","sources":["../../../src/memory/tools/MemoryDeleteTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AACpH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAM3D;;;;;;GAMG;AACH,MAAM,WAAW,iBAAkB,SAAQ,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;CAClB;AAMD;;;;;;;;;;;;;GAaG;AACH,qBAAa,gBAAiB,YAAW,KAAK,CAAC,iBAAiB,EAAE,kBAAkB,CAAC;IAyCvE,OAAO,CAAC,QAAQ,CAAC,KAAK;IAxClC,uCAAuC;IACvC,QAAQ,CAAC,EAAE,sBAAsB;IAEjC,4BAA4B;IAC5B,QAAQ,CAAC,IAAI,mBAAmB;IAEhC,mCAAmC;IACnC,QAAQ,CAAC,WAAW,mBAAmB;IAEvC,8BAA8B;IAC9B,QAAQ,CAAC,WAAW,SAG+C;IAEnE,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,YAAY;IAE7B,wCAAwC;IACxC,QAAQ,CAAC,cAAc,QAAQ;IAE/B,uEAAuE;IACvE,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAapC;IAEF;;OAEG;gBAC0B,KAAK,EAAE,WAAW;IAM/C;;;;;;;;;;OAUG;IACG,OAAO,CACX,IAAI,EAAE,iBAAiB,EACvB,QAAQ,EAAE,oBAAoB,GAC7B,OAAO,CAAC,mBAAmB,CAAC,kBAAkB,CAAC,CAAC;CAcpD"}

package/dist/memory/tools/MemoryDeleteTool.js

@@ -0,0 +1,96 @@
+/**
+ * @fileoverview MemoryDeleteTool — lets an agent soft-delete a memory trace.
+ *
+ * Deletion is always a soft-delete: the row in `memory_traces` is kept intact
+ * but its `deleted` flag is set to `1`. This preserves the audit trail and
+ * allows the consolidation engine to later log or compact the removal.
+ *
+ * The optional `reason` argument is currently captured in the tool contract
+ * but not stored in the database; it is reserved for a future `deleted_reason`
+ * column when schema migration tooling is in place.
+ *
+ * @module memory/tools/MemoryDeleteTool
+ */
+// ---------------------------------------------------------------------------
+// MemoryDeleteTool
+// ---------------------------------------------------------------------------
+/**
+ * ITool implementation that soft-deletes a memory trace from the agent's
+ * SQLite brain database.
+ *
+ * **Usage:**
+ * ```ts
+ * const tool = new MemoryDeleteTool(brain);
+ * const result = await tool.execute(
+ *   { traceId: 'mt_1711234567890_0', reason: 'Information is outdated.' },
+ *   context,
+ * );
+ * // result.output.deleted → true
+ * ```
+ */
+export class MemoryDeleteTool {
+    /**
+     * @param brain - The agent's shared SQLite brain database connection.
+     */
+    constructor(brain) {
+        this.brain = brain;
+        /** Globally unique tool identifier. */
+        this.id = 'memory-delete-v1';
+        /** LLM-facing tool name. */
+        this.name = 'memory_delete';
+        /** Human-readable display name. */
+        this.displayName = 'Delete Memory';
+        /** LLM-facing description. */
+        this.description = 'Soft-delete a memory trace by ID. The trace is not physically removed — ' +
+            'it is flagged as deleted and excluded from future searches and consolidation. ' +
+            'Use when a fact is outdated, incorrect, or no longer relevant.';
+        /** Logical category for discovery and grouping. */
+        this.category = 'memory';
+        /** This tool writes to the database. */
+        this.hasSideEffects = true;
+        /** JSON schema for input validation and LLM tool-call construction. */
+        this.inputSchema = {
+            type: 'object',
+            properties: {
+                traceId: {
+                    type: 'string',
+                    description: 'The unique ID of the memory trace to delete.',
+                },
+                reason: {
+                    type: 'string',
+                    description: 'Optional human-readable reason for deleting this memory.',
+                },
+            },
+            required: ['traceId'],
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // execute
+    // ---------------------------------------------------------------------------
+    /**
+     * Set `deleted = 1` on the memory trace matching `traceId`.
+     *
+     * The WHERE clause filters to `deleted = 0` so that attempting to
+     * delete an already-deleted trace returns `{ deleted: false }` rather
+     * than silently succeeding — this gives callers accurate feedback.
+     *
+     * @param args     - Delete input (traceId, optional reason).
+     * @param _context - Tool execution context (not used by this tool).
+     * @returns `{ deleted }` status, or an error result.
+     */
+    async execute(args, _context) {
+        try {
+            const info = this.brain.db
+                .prepare(`UPDATE memory_traces SET deleted = 1 WHERE id = ? AND deleted = 0`)
+                .run(args.traceId);
+            return { success: true, output: { deleted: info.changes > 0 } };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+}
+//# sourceMappingURL=MemoryDeleteTool.js.map

package/dist/memory/tools/MemoryDeleteTool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MemoryDeleteTool.js","sourceRoot":"","sources":["../../../src/memory/tools/MemoryDeleteTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA+BH,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,gBAAgB;IAsC3B;;OAEG;IACH,YAA6B,KAAkB;QAAlB,UAAK,GAAL,KAAK,CAAa;QAxC/C,uCAAuC;QAC9B,OAAE,GAAG,kBAAkB,CAAC;QAEjC,4BAA4B;QACnB,SAAI,GAAG,eAAe,CAAC;QAEhC,mCAAmC;QAC1B,gBAAW,GAAG,eAAe,CAAC;QAEvC,8BAA8B;QACrB,gBAAW,GAClB,0EAA0E;YAC1E,gFAAgF;YAChF,gEAAgE,CAAC;QAEnE,mDAAmD;QAC1C,aAAQ,GAAG,QAAQ,CAAC;QAE7B,wCAAwC;QAC/B,mBAAc,GAAG,IAAI,CAAC;QAE/B,uEAAuE;QAC9D,gBAAW,GAAqB;YACvC,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,OAAO,EAAE;oBACP,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,8CAA8C;iBAC5D;gBACD,MAAM,EAAE;oBACN,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,0DAA0D;iBACxE;aACF;YACD,QAAQ,EAAE,CAAC,SAAS,CAAC;SACtB,CAAC;IAKgD,CAAC;IAEnD,8EAA8E;IAC9E,UAAU;IACV,8EAA8E;IAE9E;;;;;;;;;;OAUG;IACH,KAAK,CAAC,OAAO,CACX,IAAuB,EACvB,QAA8B;QAE9B,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE;iBACvB,OAAO,CAAC,mEAAmE,CAAC;iBAC5E,GAAG,CAAC,IAAI,CAAC,OAAO,CAAwB,CAAC;YAE5C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,GAAG,CAAC,EAAE,EAAE,CAAC;QAClE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;aACxD,CAAC;QACJ,CAAC;IACH,CAAC;CACF"}

package/dist/memory/tools/MemoryMergeTool.d.ts

@@ -0,0 +1,95 @@
+/**
+ * @fileoverview MemoryMergeTool — lets an agent merge multiple memory traces
+ * into a single, consolidated trace.
+ *
+ * The merge process:
+ * 1. Load all specified traces from the database.
+ * 2. Select the survivor — the trace with the highest `retrieval_count`
+ *    (most-frequently accessed, i.e. most valuable). Ties broken by taking
+ *    the first trace in the provided `traceIds` array.
+ * 3. Determine merged content — use `mergedContent` if the agent supplied it,
+ *    otherwise concatenate all trace contents with ` | ` as separator.
+ * 4. Update the survivor's content, clear its embedding (stale after merge),
+ *    and union the tags from all merged traces (deduplicated).
+ * 5. Soft-delete all non-survivor traces.
+ *
+ * @module memory/tools/MemoryMergeTool
+ */
+import type { ITool, ToolExecutionResult, ToolExecutionContext, JSONSchemaObject } from '../../core/tools/ITool.js';
+import type { SqliteBrain } from '../store/SqliteBrain.js';
+/**
+ * Input arguments for {@link MemoryMergeTool}.
+ *
+ * @property traceIds      - Array of trace IDs to merge. Must contain at least 2 IDs.
+ * @property mergedContent - Optional pre-composed merged content. If omitted, the
+ *                           contents of all traces are concatenated with ` | `.
+ */
+export interface MemoryMergeInput extends Record<string, any> {
+    traceIds: string[];
+    mergedContent?: string;
+}
+/**
+ * Output returned by {@link MemoryMergeTool} on success.
+ *
+ * @property survivorId  - The ID of the trace that survived the merge.
+ * @property deletedIds  - IDs of all traces that were soft-deleted.
+ */
+export interface MemoryMergeOutput {
+    survivorId: string;
+    deletedIds: string[];
+}
+/**
+ * ITool implementation that merges multiple memory traces into one.
+ *
+ * **Usage:**
+ * ```ts
+ * 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'] }
+ * ```
+ */
+export declare class MemoryMergeTool implements ITool<MemoryMergeInput, MemoryMergeOutput> {
+    private readonly brain;
+    /** Globally unique tool identifier. */
+    readonly id = "memory-merge-v1";
+    /** LLM-facing tool name. */
+    readonly name = "memory_merge";
+    /** Human-readable display name. */
+    readonly displayName = "Merge Memories";
+    /** LLM-facing description. */
+    readonly description: string;
+    /** Logical category for discovery and grouping. */
+    readonly category = "memory";
+    /** This tool writes to the database. */
+    readonly hasSideEffects = true;
+    /** JSON schema for input validation and LLM tool-call construction. */
+    readonly inputSchema: JSONSchemaObject;
+    /**
+     * @param brain - The agent's shared SQLite brain database connection.
+     */
+    constructor(brain: SqliteBrain);
+    /**
+     * 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`; fallback to first found.
+     * 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.
+     *
+     * @param args     - Merge input (traceIds, optional mergedContent).
+     * @param _context - Tool execution context (not used by this tool).
+     * @returns `{ survivorId, deletedIds }` on success, or an error result.
+     */
+    execute(args: MemoryMergeInput, _context: ToolExecutionContext): Promise<ToolExecutionResult<MemoryMergeOutput>>;
+}
+//# sourceMappingURL=MemoryMergeTool.d.ts.map

package/dist/memory/tools/MemoryMergeTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MemoryMergeTool.d.ts","sourceRoot":"","sources":["../../../src/memory/tools/MemoryMergeTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AACpH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAkB3D;;;;;;GAMG;AACH,MAAM,WAAW,gBAAiB,SAAQ,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAC3D,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAMD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,eAAgB,YAAW,KAAK,CAAC,gBAAgB,EAAE,iBAAiB,CAAC;IA4CpE,OAAO,CAAC,QAAQ,CAAC,KAAK;IA3ClC,uCAAuC;IACvC,QAAQ,CAAC,EAAE,qBAAqB;IAEhC,4BAA4B;IAC5B,QAAQ,CAAC,IAAI,kBAAkB;IAE/B,mCAAmC;IACnC,QAAQ,CAAC,WAAW,oBAAoB;IAExC,8BAA8B;IAC9B,QAAQ,CAAC,WAAW,SAGsE;IAE1F,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,YAAY;IAE7B,wCAAwC;IACxC,QAAQ,CAAC,cAAc,QAAQ;IAE/B,uEAAuE;IACvE,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAgBpC;IAEF;;OAEG;gBAC0B,KAAK,EAAE,WAAW;IAM/C;;;;;;;;;;;;;;;OAeG;IACG,OAAO,CACX,IAAI,EAAE,gBAAgB,EACtB,QAAQ,EAAE,oBAAoB,GAC7B,OAAO,CAAC,mBAAmB,CAAC,iBAAiB,CAAC,CAAC;CAmFnD"}