@framers/agentos 0.1.126 → 0.1.127

package/dist/memory/store/tracePersistence.js

@@ -1,159 +0,0 @@
-/**
- * @fileoverview Shared helpers for persisting trace metadata in SQLite-first
- * memory paths.
- *
- * The Phase 1 memory facade stores core retrieval counters in dedicated
- * columns, but richer decay state is persisted inside `memory_traces.metadata`
- * to avoid a schema expansion. These helpers keep that JSON contract
- * consistent across the facade, consolidation loop, feedback loop, and
- * agent-facing memory tools.
- *
- * @module memory/store/tracePersistence
- */
-import { sha256 } from '../util/crossPlatformCrypto.js';
-/**
- * Default stability for traces that do not yet have an explicit persisted
- * decay state.
- */
-export const DEFAULT_TRACE_STABILITY_MS = 86400000;
-/**
- * Default reinforcement interval for traces that do not yet have an explicit
- * persisted decay state.
- */
-export const DEFAULT_TRACE_REINFORCEMENT_INTERVAL_MS = 86400000;
-const FTS_STOP_WORDS = new Set([
-    'a',
-    'an',
-    'and',
-    'are',
-    'as',
-    'at',
-    'be',
-    'by',
-    'for',
-    'from',
-    'how',
-    'i',
-    'in',
-    'is',
-    'it',
-    'me',
-    'my',
-    'of',
-    'on',
-    'or',
-    'our',
-    'the',
-    'to',
-    'us',
-    'we',
-    'what',
-    'when',
-    'where',
-    'who',
-    'why',
-    'with',
-    'you',
-    'your',
-]);
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-function finiteNumber(value) {
-    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
-}
-/**
- * Parse a raw `metadata` JSON string into a plain object.
- */
-export function parseTraceMetadata(raw) {
-    if (!raw)
-        return {};
-    try {
-        const parsed = JSON.parse(raw);
-        return isRecord(parsed) ? parsed : {};
-    }
-    catch {
-        return {};
-    }
-}
-/**
- * Read the persisted decay state from a metadata object, applying defaults
- * when fields are absent.
- */
-export function readPersistedDecayState(metadata, retrievalCount = 0) {
-    const decay = isRecord(metadata.decay) ? metadata.decay : {};
-    const nextReinforcementAt = finiteNumber(decay.nextReinforcementAt);
-    return {
-        stability: finiteNumber(decay.stability) ?? DEFAULT_TRACE_STABILITY_MS,
-        accessCount: finiteNumber(decay.accessCount) ?? retrievalCount,
-        reinforcementInterval: finiteNumber(decay.reinforcementInterval) ?? DEFAULT_TRACE_REINFORCEMENT_INTERVAL_MS,
-        ...(nextReinforcementAt !== undefined ? { nextReinforcementAt } : {}),
-    };
-}
-/**
- * Merge a decay state payload into an existing metadata object.
- */
-export function withPersistedDecayState(metadata, state) {
-    const nextDecay = {
-        stability: state.stability,
-        accessCount: state.accessCount,
-        reinforcementInterval: state.reinforcementInterval,
-    };
-    if (state.nextReinforcementAt !== undefined) {
-        nextDecay.nextReinforcementAt = state.nextReinforcementAt;
-    }
-    return {
-        ...metadata,
-        decay: nextDecay,
-    };
-}
-/**
- * Build initial metadata for a newly inserted memory trace.
- */
-export function buildInitialTraceMetadata(baseMetadata = {}, options) {
-    const metadata = { ...baseMetadata };
-    if (options?.contentHash !== undefined) {
-        metadata.content_hash = options.contentHash;
-    }
-    if (options?.entities !== undefined) {
-        metadata.entities = options.entities;
-    }
-    if (options?.scopeId !== undefined) {
-        metadata.scopeId = options.scopeId;
-    }
-    return withPersistedDecayState(metadata, {
-        stability: options?.stability ?? DEFAULT_TRACE_STABILITY_MS,
-        accessCount: options?.accessCount ?? 0,
-        reinforcementInterval: options?.reinforcementInterval ?? DEFAULT_TRACE_REINFORCEMENT_INTERVAL_MS,
-        ...(options?.nextReinforcementAt !== undefined
-            ? { nextReinforcementAt: options.nextReinforcementAt }
-            : {}),
-    });
-}
-/**
- * Compute a SHA-256 hex digest for trace content.
- */
-export async function sha256Hex(content) {
-    return sha256(content);
-}
-/**
- * Convert free-form natural language into a conservative FTS5 query.
- *
- * This avoids syntax errors when callers pass punctuation-heavy questions such
- * as "What are my workflow preferences?" into a raw `MATCH` clause.
- */
-export function buildNaturalLanguageFtsQuery(query) {
-    const trimmed = query.trim();
-    if (!trimmed)
-        return '';
-    const rawTokens = Array.from(new Set((trimmed.match(/[\p{L}\p{N}_]+/gu) ?? [])
-        .map((token) => token.toLowerCase())
-        .filter(Boolean)));
-    if (rawTokens.length === 0) {
-        return '';
-    }
-    const filteredTokens = rawTokens.filter((token) => token.length > 1 && !FTS_STOP_WORDS.has(token));
-    const tokens = filteredTokens.length > 0 ? filteredTokens : rawTokens;
-    return tokens.map((token) => `${token}*`).join(' OR ');
-}
-//# sourceMappingURL=tracePersistence.js.map

package/dist/memory/store/tracePersistence.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"tracePersistence.js","sourceRoot":"","sources":["../../../src/memory/store/tracePersistence.ts"],"names":[],"mappings":"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"}

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

@@ -1,98 +0,0 @@
-/**
- * @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 used to resolve the scope ID.
-     * @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

@@ -1 +0,0 @@
-{"version":3,"file":"MemoryAddTool.d.ts","sourceRoot":"","sources":["../../../src/memory/tools/MemoryAddTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACV,KAAK,EACL,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EACjB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAe3D;;;;;;;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,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,mBAAmB,CAAC,eAAe,CAAC,CAAC;CA0CjD"}

package/dist/memory/tools/MemoryAddTool.js

@@ -1,139 +0,0 @@
-/**
- * @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 { buildInitialTraceMetadata, sha256Hex } from '../store/tracePersistence.js';
-import { resolveMemoryToolScopeId } from './scopeContext.js';
-// ---------------------------------------------------------------------------
-// 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 used to resolve the scope ID.
-     * @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 scopeId = resolveMemoryToolScopeId(scope, context);
-            const tags = JSON.stringify(args.tags ?? []);
-            const metadata = JSON.stringify(buildInitialTraceMetadata({}, {
-                contentHash: await sha256Hex(args.content),
-                ...(scopeId ? { scopeId } : {}),
-            }));
-            await this.brain.transaction(async (trx) => {
-                await trx.run(`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)`, [traceId, type, scope, args.content, now, tags, metadata]);
-                await trx.run(this.brain.features.fts.syncInsert('memory_traces_fts', '(SELECT rowid FROM memory_traces WHERE id = ?)', ['content', 'tags']), [traceId, args.content, 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

@@ -1 +0,0 @@
-{"version":3,"file":"MemoryAddTool.js","sourceRoot":"","sources":["../../../src/memory/tools/MemoryAddTool.ts"],"names":[],"mappings":"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"}

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

@@ -1,83 +0,0 @@
-/**
- * @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

@@ -1 +0,0 @@
-{"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;CAepD"}

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

@@ -1 +0,0 @@
-{"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,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAC/B,mEAAmE,EACnE,CAAC,IAAI,CAAC,OAAO,CAAC,CACf,CAAC;YAEF,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

@@ -1,95 +0,0 @@
-/**
- * @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

@@ -1 +0,0 @@
-{"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;AA4B3D;;;;;;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;CAyHnD"}