@framers/agentos 0.1.101 → 0.1.103

package/dist/memory/tools/MemoryMergeTool.js

@@ -0,0 +1,164 @@
+/**
+ * @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
+ */
+// ---------------------------------------------------------------------------
+// MemoryMergeTool
+// ---------------------------------------------------------------------------
+/**
+ * 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 class MemoryMergeTool {
+    /**
+     * @param brain - The agent's shared SQLite brain database connection.
+     */
+    constructor(brain) {
+        this.brain = brain;
+        /** Globally unique tool identifier. */
+        this.id = 'memory-merge-v1';
+        /** LLM-facing tool name. */
+        this.name = 'memory_merge';
+        /** Human-readable display name. */
+        this.displayName = 'Merge Memories';
+        /** LLM-facing description. */
+        this.description = 'Merge two or more memory traces into a single consolidated trace. ' +
+            'The trace with the highest retrieval count survives; others are soft-deleted. ' +
+            'Optionally provide pre-composed merged content; otherwise, contents are concatenated.';
+        /** 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: {
+                traceIds: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    minItems: 2,
+                    description: 'Array of trace IDs to merge. Must contain at least 2 IDs.',
+                },
+                mergedContent: {
+                    type: 'string',
+                    description: 'Optional pre-composed merged content. If omitted, trace contents are joined with " | ".',
+                },
+            },
+            required: ['traceIds'],
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // execute
+    // ---------------------------------------------------------------------------
+    /**
+     * 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.
+     */
+    async execute(args, _context) {
+        try {
+            const { traceIds, mergedContent } = args;
+            if (!traceIds || traceIds.length < 2) {
+                return {
+                    success: false,
+                    error: 'traceIds must contain at least 2 trace IDs.',
+                };
+            }
+            // Load all matching active traces.
+            const placeholders = traceIds.map(() => '?').join(', ');
+            const rows = this.brain.db
+                .prepare(`SELECT id, content, retrieval_count, tags
+           FROM memory_traces
+           WHERE id IN (${placeholders}) AND deleted = 0`)
+                .all(...traceIds);
+            if (rows.length < 2) {
+                return {
+                    success: false,
+                    error: `Found only ${rows.length} active trace(s) for the provided IDs. Need at least 2.`,
+                };
+            }
+            // Pick survivor — trace with highest retrieval_count.
+            // Stable sort: keeps original order for equal counts so the first traceId wins.
+            const sorted = [...rows].sort((a, b) => b.retrieval_count - a.retrieval_count);
+            const survivor = sorted[0];
+            // Determine merged content.
+            const finalContent = mergedContent !== undefined && mergedContent.trim().length > 0
+                ? mergedContent
+                : rows.map((r) => r.content).join(' | ');
+            // Union tags from all traces (deduplicated).
+            const allTags = new Set();
+            for (const row of rows) {
+                try {
+                    const parsed = JSON.parse(row.tags);
+                    for (const tag of parsed)
+                        allTags.add(tag);
+                }
+                catch {
+                    // Malformed JSON tag — skip gracefully.
+                }
+            }
+            // Update survivor: new content, cleared embedding, unioned tags.
+            this.brain.db
+                .prepare(`UPDATE memory_traces
+           SET content = ?, embedding = NULL, tags = ?
+           WHERE id = ?`)
+                .run(finalContent, JSON.stringify([...allTags]), survivor.id);
+            // Soft-delete all non-survivors.
+            const deletedIds = [];
+            const deleteStmt = this.brain.db.prepare(`UPDATE memory_traces SET deleted = 1 WHERE id = ?`);
+            for (const row of rows) {
+                if (row.id !== survivor.id) {
+                    deleteStmt.run(row.id);
+                    deletedIds.push(row.id);
+                }
+            }
+            return {
+                success: true,
+                output: { survivorId: survivor.id, deletedIds },
+            };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+}
+//# sourceMappingURL=MemoryMergeTool.js.map

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

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

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

@@ -0,0 +1,86 @@
+/**
+ * @fileoverview MemoryReflectTool — lets an agent trigger offline memory
+ * consolidation on demand.
+ *
+ * Consolidation is the analogue of slow-wave-sleep memory processing:
+ * - **Prune** — soft-delete traces whose Ebbinghaus strength has decayed below threshold.
+ * - **Merge** — deduplicate near-identical traces (embedding similarity or hash).
+ * - **Strengthen** — record Hebbian co-activation edges from retrieval feedback.
+ * - **Derive** — synthesise higher-level insight traces from memory clusters (LLM-backed).
+ * - **Compact** — promote old, high-retrieval episodic traces to semantic type.
+ * - **Re-index** — rebuild FTS5 index and log the run to `consolidation_log`.
+ *
+ * The optional `topic` argument is accepted at the contract level but is not
+ * yet threaded into the ConsolidationLoop (which currently runs globally).
+ * It is reserved for a future topic-scoped consolidation mode.
+ *
+ * @module memory/tools/MemoryReflectTool
+ */
+import type { ITool, ToolExecutionResult, ToolExecutionContext, JSONSchemaObject } from '../../core/tools/ITool.js';
+import type { ConsolidationLoop } from '../consolidation/ConsolidationLoop.js';
+import type { ConsolidationResult } from '../facade/types.js';
+import type { SqliteBrain } from '../store/SqliteBrain.js';
+/**
+ * Input arguments for {@link MemoryReflectTool}.
+ *
+ * @property topic - Optional hint for the consolidation run. Currently reserved
+ *                   for future topic-scoped consolidation; ignored at runtime.
+ */
+export interface MemoryReflectInput extends Record<string, any> {
+    topic?: string;
+}
+/**
+ * ITool implementation that triggers one full memory consolidation cycle via
+ * {@link ConsolidationLoop.run()}.
+ *
+ * **Usage:**
+ * ```ts
+ * const tool = new MemoryReflectTool(brain, consolidationLoop);
+ * const result = await tool.execute({}, context);
+ * // result.output → { pruned: 3, merged: 1, derived: 0, compacted: 2, durationMs: 42 }
+ * ```
+ */
+export declare class MemoryReflectTool implements ITool<MemoryReflectInput, ConsolidationResult> {
+    private readonly brain;
+    private readonly consolidation;
+    /** Globally unique tool identifier. */
+    readonly id = "memory-reflect-v1";
+    /** LLM-facing tool name. */
+    readonly name = "memory_reflect";
+    /** Human-readable display name. */
+    readonly displayName = "Reflect on Memory";
+    /**
+     * Description shown to the LLM. The consolidation steps are described
+     * explicitly so the model understands what "reflect" means operationally.
+     */
+    readonly description: string;
+    /** Logical category for discovery and grouping. */
+    readonly category = "memory";
+    /**
+     * Consolidation writes to the database (pruning, merging, inserting insights).
+     * Mark as having side effects so callers may request confirmation if needed.
+     */
+    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.
+     *                        Accepted for symmetry with other memory tools and for
+     *                        future direct consolidation calls.
+     * @param consolidation - The {@link ConsolidationLoop} instance to invoke.
+     */
+    constructor(brain: SqliteBrain, consolidation: ConsolidationLoop);
+    /**
+     * Run one full consolidation cycle and return the statistics.
+     *
+     * If a consolidation cycle is already in progress (mutex guard in
+     * {@link ConsolidationLoop}), `run()` returns immediately with zero counts —
+     * this is surfaced as a successful result with all-zero statistics.
+     *
+     * @param _args    - Reflect input (optional topic hint, currently unused).
+     * @param _context - Tool execution context (not used by this tool).
+     * @returns {@link ConsolidationResult} on success, or an error result.
+     */
+    execute(_args: MemoryReflectInput, _context: ToolExecutionContext): Promise<ToolExecutionResult<ConsolidationResult>>;
+}
+//# sourceMappingURL=MemoryReflectTool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"MemoryReflectTool.d.ts","sourceRoot":"","sources":["../../../src/memory/tools/MemoryReflectTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AACpH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAC/E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAM3D;;;;;GAKG;AACH,MAAM,WAAW,kBAAmB,SAAQ,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAMD;;;;;;;;;;GAUG;AACH,qBAAa,iBAAkB,YAAW,KAAK,CAAC,kBAAkB,EAAE,mBAAmB,CAAC;IAgDpF,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAhDhC,uCAAuC;IACvC,QAAQ,CAAC,EAAE,uBAAuB;IAElC,4BAA4B;IAC5B,QAAQ,CAAC,IAAI,oBAAoB;IAEjC,mCAAmC;IACnC,QAAQ,CAAC,WAAW,uBAAuB;IAE3C;;;OAGG;IACH,QAAQ,CAAC,WAAW,SAIgF;IAEpG,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,YAAY;IAE7B;;;OAGG;IACH,QAAQ,CAAC,cAAc,QAAQ;IAE/B,uEAAuE;IACvE,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CASpC;IAEF;;;;;OAKG;gBAEgB,KAAK,EAAE,WAAW,EAClB,aAAa,EAAE,iBAAiB;IAOnD;;;;;;;;;;OAUG;IACG,OAAO,CACX,KAAK,EAAE,kBAAkB,EACzB,QAAQ,EAAE,oBAAoB,GAC7B,OAAO,CAAC,mBAAmB,CAAC,mBAAmB,CAAC,CAAC;CAWrD"}

package/dist/memory/tools/MemoryReflectTool.js

@@ -0,0 +1,102 @@
+/**
+ * @fileoverview MemoryReflectTool — lets an agent trigger offline memory
+ * consolidation on demand.
+ *
+ * Consolidation is the analogue of slow-wave-sleep memory processing:
+ * - **Prune** — soft-delete traces whose Ebbinghaus strength has decayed below threshold.
+ * - **Merge** — deduplicate near-identical traces (embedding similarity or hash).
+ * - **Strengthen** — record Hebbian co-activation edges from retrieval feedback.
+ * - **Derive** — synthesise higher-level insight traces from memory clusters (LLM-backed).
+ * - **Compact** — promote old, high-retrieval episodic traces to semantic type.
+ * - **Re-index** — rebuild FTS5 index and log the run to `consolidation_log`.
+ *
+ * The optional `topic` argument is accepted at the contract level but is not
+ * yet threaded into the ConsolidationLoop (which currently runs globally).
+ * It is reserved for a future topic-scoped consolidation mode.
+ *
+ * @module memory/tools/MemoryReflectTool
+ */
+// ---------------------------------------------------------------------------
+// MemoryReflectTool
+// ---------------------------------------------------------------------------
+/**
+ * ITool implementation that triggers one full memory consolidation cycle via
+ * {@link ConsolidationLoop.run()}.
+ *
+ * **Usage:**
+ * ```ts
+ * const tool = new MemoryReflectTool(brain, consolidationLoop);
+ * const result = await tool.execute({}, context);
+ * // result.output → { pruned: 3, merged: 1, derived: 0, compacted: 2, durationMs: 42 }
+ * ```
+ */
+export class MemoryReflectTool {
+    /**
+     * @param brain         - The agent's shared SQLite brain database connection.
+     *                        Accepted for symmetry with other memory tools and for
+     *                        future direct consolidation calls.
+     * @param consolidation - The {@link ConsolidationLoop} instance to invoke.
+     */
+    constructor(brain, consolidation) {
+        this.brain = brain;
+        this.consolidation = consolidation;
+        /** Globally unique tool identifier. */
+        this.id = 'memory-reflect-v1';
+        /** LLM-facing tool name. */
+        this.name = 'memory_reflect';
+        /** Human-readable display name. */
+        this.displayName = 'Reflect on Memory';
+        /**
+         * Description shown to the LLM. The consolidation steps are described
+         * explicitly so the model understands what "reflect" means operationally.
+         */
+        this.description = 'Trigger memory consolidation — prune weak memories, merge duplicates, derive insights from patterns. ' +
+            'This runs an offline slow-wave-sleep analogue: decayed traces are pruned, near-identical traces are ' +
+            'merged, Hebbian co-activation edges are recorded, insights are derived from clusters, and old ' +
+            'high-retrieval episodic traces are promoted to semantic type. Returns consolidation statistics.';
+        /** Logical category for discovery and grouping. */
+        this.category = 'memory';
+        /**
+         * Consolidation writes to the database (pruning, merging, inserting insights).
+         * Mark as having side effects so callers may request confirmation if needed.
+         */
+        this.hasSideEffects = true;
+        /** JSON schema for input validation and LLM tool-call construction. */
+        this.inputSchema = {
+            type: 'object',
+            properties: {
+                topic: {
+                    type: 'string',
+                    description: 'Optional topic hint for the consolidation run. Reserved for future topic-scoped consolidation.',
+                },
+            },
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // execute
+    // ---------------------------------------------------------------------------
+    /**
+     * Run one full consolidation cycle and return the statistics.
+     *
+     * If a consolidation cycle is already in progress (mutex guard in
+     * {@link ConsolidationLoop}), `run()` returns immediately with zero counts —
+     * this is surfaced as a successful result with all-zero statistics.
+     *
+     * @param _args    - Reflect input (optional topic hint, currently unused).
+     * @param _context - Tool execution context (not used by this tool).
+     * @returns {@link ConsolidationResult} on success, or an error result.
+     */
+    async execute(_args, _context) {
+        try {
+            const result = await this.consolidation.run();
+            return { success: true, output: result };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+}
+//# sourceMappingURL=MemoryReflectTool.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"MemoryReflectTool.js","sourceRoot":"","sources":["../../../src/memory/tools/MemoryReflectTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAqBH,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E;;;;;;;;;;GAUG;AACH,MAAM,OAAO,iBAAiB;IAyC5B;;;;;OAKG;IACH,YACmB,KAAkB,EAClB,aAAgC;QADhC,UAAK,GAAL,KAAK,CAAa;QAClB,kBAAa,GAAb,aAAa,CAAmB;QAhDnD,uCAAuC;QAC9B,OAAE,GAAG,mBAAmB,CAAC;QAElC,4BAA4B;QACnB,SAAI,GAAG,gBAAgB,CAAC;QAEjC,mCAAmC;QAC1B,gBAAW,GAAG,mBAAmB,CAAC;QAE3C;;;WAGG;QACM,gBAAW,GAClB,uGAAuG;YACvG,sGAAsG;YACtG,gGAAgG;YAChG,iGAAiG,CAAC;QAEpG,mDAAmD;QAC1C,aAAQ,GAAG,QAAQ,CAAC;QAE7B;;;WAGG;QACM,mBAAc,GAAG,IAAI,CAAC;QAE/B,uEAAuE;QAC9D,gBAAW,GAAqB;YACvC,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,WAAW,EACT,gGAAgG;iBACnG;aACF;SACF,CAAC;IAWC,CAAC;IAEJ,8EAA8E;IAC9E,UAAU;IACV,8EAA8E;IAE9E;;;;;;;;;;OAUG;IACH,KAAK,CAAC,OAAO,CACX,KAAyB,EACzB,QAA8B;QAE9B,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,GAAG,EAAE,CAAC;YAC9C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;QAC3C,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/MemorySearchTool.d.ts

@@ -0,0 +1,117 @@
+/**
+ * @fileoverview MemorySearchTool — lets an agent search its own memory traces
+ * using FTS5 full-text search.
+ *
+ * The tool queries the `memory_traces_fts` FTS5 virtual table (backed by the
+ * `memory_traces` content table) and joins back to `memory_traces` for
+ * metadata fields (type, scope, strength, tags). Optional `type` and `scope`
+ * filters narrow the result set via SQL WHERE clauses applied to the join.
+ *
+ * FTS5 matching uses the Porter-stemmed tokenizer configured at DDL time, so
+ * queries like `"retrieve"` will also match `"retrieval"`, `"retrieved"`, etc.
+ *
+ * @module memory/tools/MemorySearchTool
+ */
+import type { ITool, ToolExecutionResult, ToolExecutionContext, JSONSchemaObject } from '../../core/tools/ITool.js';
+import type { SqliteBrain } from '../store/SqliteBrain.js';
+/**
+ * Input arguments for {@link MemorySearchTool}.
+ *
+ * @property query - The full-text search query string. Supports FTS5 syntax
+ *                   (phrase queries in quotes, boolean operators, prefix matching).
+ * @property type  - Optional filter: only return traces of this Tulving memory type.
+ * @property scope - Optional filter: only return traces with this visibility scope.
+ * @property limit - Maximum number of results to return. Defaults to 10.
+ */
+export interface MemorySearchInput extends Record<string, any> {
+    query: string;
+    type?: string;
+    scope?: string;
+    limit?: number;
+}
+/**
+ * A single result item in the {@link MemorySearchOutput} results array.
+ *
+ * @property id       - Trace ID.
+ * @property content  - Full text content of the trace.
+ * @property type     - Tulving memory type.
+ * @property scope    - Visibility scope.
+ * @property strength - Current Ebbinghaus encoding strength (0–1).
+ * @property tags     - Array of tag strings.
+ */
+export interface MemorySearchResult {
+    id: string;
+    content: string;
+    type: string;
+    scope: string;
+    strength: number;
+    tags: string[];
+}
+/**
+ * Output returned by {@link MemorySearchTool} on success.
+ *
+ * @property results - Array of matching memory traces ordered by FTS5 relevance (BM25).
+ */
+export interface MemorySearchOutput {
+    results: MemorySearchResult[];
+}
+/**
+ * ITool implementation that searches the agent's memory traces using FTS5.
+ *
+ * **Usage:**
+ * ```ts
+ * const tool = new MemorySearchTool(brain);
+ * const result = await tool.execute(
+ *   { query: 'dark mode preference', scope: 'user', limit: 5 },
+ *   context,
+ * );
+ * // result.output.results → [{ id, content, type, scope, strength, tags }, ...]
+ * ```
+ */
+export declare class MemorySearchTool implements ITool<MemorySearchInput, MemorySearchOutput> {
+    private readonly brain;
+    /** Globally unique tool identifier. */
+    readonly id = "memory-search-v1";
+    /** LLM-facing tool name. */
+    readonly name = "memory_search";
+    /** Human-readable display name. */
+    readonly displayName = "Search Memory";
+    /** LLM-facing description. */
+    readonly description: string;
+    /** Logical category for discovery and grouping. */
+    readonly category = "memory";
+    /** This tool only reads from the database — no side effects. */
+    readonly hasSideEffects = false;
+    /** 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);
+    /**
+     * Run a full-text search against `memory_traces_fts` and join back to
+     * `memory_traces` for metadata.
+     *
+     * The SQL pattern:
+     * ```sql
+     * SELECT mt.id, mt.content, mt.type, mt.scope, mt.strength, mt.tags
+     * FROM memory_traces_fts fts
+     * JOIN memory_traces mt ON mt.rowid = fts.rowid
+     * WHERE fts.memory_traces_fts MATCH ?
+     *   AND mt.deleted = 0
+     *   [AND mt.type = ?]    -- when type filter provided
+     *   [AND mt.scope = ?]   -- when scope filter provided
+     * ORDER BY rank          -- FTS5 BM25 relevance (lower = more relevant)
+     * LIMIT ?
+     * ```
+     *
+     * Tags are stored as JSON arrays; they are parsed and returned as string[].
+     * Malformed tag JSON returns an empty array rather than throwing.
+     *
+     * @param args     - Search input (query, optional type/scope/limit).
+     * @param _context - Tool execution context (not used by this tool).
+     * @returns `{ results }` array on success, or an error result.
+     */
+    execute(args: MemorySearchInput, _context: ToolExecutionContext): Promise<ToolExecutionResult<MemorySearchOutput>>;
+}
+//# sourceMappingURL=MemorySearchTool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"MemorySearchTool.d.ts","sourceRoot":"","sources":["../../../src/memory/tools/MemorySearchTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AACpH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAoB3D;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAkB,SAAQ,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAC5D,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,kBAAkB,EAAE,CAAC;CAC/B;AAMD;;;;;;;;;;;;GAYG;AACH,qBAAa,gBAAiB,YAAW,KAAK,CAAC,iBAAiB,EAAE,kBAAkB,CAAC;IAsDvE,OAAO,CAAC,QAAQ,CAAC,KAAK;IArDlC,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,SAGuF;IAE3G,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,YAAY;IAE7B,gEAAgE;IAChE,QAAQ,CAAC,cAAc,SAAS;IAEhC,uEAAuE;IACvE,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CA0BpC;IAEF;;OAEG;gBAC0B,KAAK,EAAE,WAAW;IAM/C;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,OAAO,CACX,IAAI,EAAE,iBAAiB,EACvB,QAAQ,EAAE,oBAAoB,GAC7B,OAAO,CAAC,mBAAmB,CAAC,kBAAkB,CAAC,CAAC;CAgEpD"}

package/dist/memory/tools/MemorySearchTool.js

@@ -0,0 +1,162 @@
+/**
+ * @fileoverview MemorySearchTool — lets an agent search its own memory traces
+ * using FTS5 full-text search.
+ *
+ * The tool queries the `memory_traces_fts` FTS5 virtual table (backed by the
+ * `memory_traces` content table) and joins back to `memory_traces` for
+ * metadata fields (type, scope, strength, tags). Optional `type` and `scope`
+ * filters narrow the result set via SQL WHERE clauses applied to the join.
+ *
+ * FTS5 matching uses the Porter-stemmed tokenizer configured at DDL time, so
+ * queries like `"retrieve"` will also match `"retrieval"`, `"retrieved"`, etc.
+ *
+ * @module memory/tools/MemorySearchTool
+ */
+// ---------------------------------------------------------------------------
+// MemorySearchTool
+// ---------------------------------------------------------------------------
+/**
+ * ITool implementation that searches the agent's memory traces using FTS5.
+ *
+ * **Usage:**
+ * ```ts
+ * const tool = new MemorySearchTool(brain);
+ * const result = await tool.execute(
+ *   { query: 'dark mode preference', scope: 'user', limit: 5 },
+ *   context,
+ * );
+ * // result.output.results → [{ id, content, type, scope, strength, tags }, ...]
+ * ```
+ */
+export class MemorySearchTool {
+    /**
+     * @param brain - The agent's shared SQLite brain database connection.
+     */
+    constructor(brain) {
+        this.brain = brain;
+        /** Globally unique tool identifier. */
+        this.id = 'memory-search-v1';
+        /** LLM-facing tool name. */
+        this.name = 'memory_search';
+        /** Human-readable display name. */
+        this.displayName = 'Search Memory';
+        /** LLM-facing description. */
+        this.description = 'Search memory traces using full-text search (FTS5 with Porter stemming). ' +
+            'Supports FTS5 query syntax: phrase queries in quotes, AND/OR operators, prefix matching (e.g. "retriev*"). ' +
+            'Filter by type (episodic/semantic/procedural/prospective) or scope (thread/user/persona/organization).';
+        /** Logical category for discovery and grouping. */
+        this.category = 'memory';
+        /** This tool only reads from the database — no side effects. */
+        this.hasSideEffects = false;
+        /** JSON schema for input validation and LLM tool-call construction. */
+        this.inputSchema = {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Full-text search query string. Supports FTS5 syntax: phrases in quotes, boolean operators, prefix matching.',
+                },
+                type: {
+                    type: 'string',
+                    enum: ['episodic', 'semantic', 'procedural', 'prospective'],
+                    description: 'Optional filter: only return traces of this memory type.',
+                },
+                scope: {
+                    type: 'string',
+                    enum: ['thread', 'user', 'persona', 'organization'],
+                    description: 'Optional filter: only return traces with this scope.',
+                },
+                limit: {
+                    type: 'integer',
+                    minimum: 1,
+                    maximum: 100,
+                    description: 'Maximum number of results to return. Defaults to 10.',
+                },
+            },
+            required: ['query'],
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // execute
+    // ---------------------------------------------------------------------------
+    /**
+     * Run a full-text search against `memory_traces_fts` and join back to
+     * `memory_traces` for metadata.
+     *
+     * The SQL pattern:
+     * ```sql
+     * SELECT mt.id, mt.content, mt.type, mt.scope, mt.strength, mt.tags
+     * FROM memory_traces_fts fts
+     * JOIN memory_traces mt ON mt.rowid = fts.rowid
+     * WHERE fts.memory_traces_fts MATCH ?
+     *   AND mt.deleted = 0
+     *   [AND mt.type = ?]    -- when type filter provided
+     *   [AND mt.scope = ?]   -- when scope filter provided
+     * ORDER BY rank          -- FTS5 BM25 relevance (lower = more relevant)
+     * LIMIT ?
+     * ```
+     *
+     * Tags are stored as JSON arrays; they are parsed and returned as string[].
+     * Malformed tag JSON returns an empty array rather than throwing.
+     *
+     * @param args     - Search input (query, optional type/scope/limit).
+     * @param _context - Tool execution context (not used by this tool).
+     * @returns `{ results }` array on success, or an error result.
+     */
+    async execute(args, _context) {
+        try {
+            const limit = args.limit ?? 10;
+            // Build WHERE clause additions for optional filters.
+            const extraClauses = [];
+            const extraParams = [];
+            if (args.type !== undefined) {
+                extraClauses.push('mt.type = ?');
+                extraParams.push(args.type);
+            }
+            if (args.scope !== undefined) {
+                extraClauses.push('mt.scope = ?');
+                extraParams.push(args.scope);
+            }
+            const extraWhere = extraClauses.length > 0 ? `AND ${extraClauses.join(' AND ')}` : '';
+            const sql = `
+        SELECT mt.id, mt.content, mt.type, mt.scope, mt.strength, mt.tags
+        FROM memory_traces_fts fts
+        JOIN memory_traces mt ON mt.rowid = fts.rowid
+        WHERE fts.memory_traces_fts MATCH ?
+          AND mt.deleted = 0
+          ${extraWhere}
+        ORDER BY rank
+        LIMIT ?
+      `;
+            const params = [args.query, ...extraParams, limit];
+            const rows = this.brain.db
+                .prepare(sql)
+                .all(...params);
+            const results = rows.map((row) => {
+                let tags = [];
+                try {
+                    tags = JSON.parse(row.tags);
+                }
+                catch {
+                    // Malformed JSON tags — return empty array.
+                }
+                return {
+                    id: row.id,
+                    content: row.content,
+                    type: row.type,
+                    scope: row.scope,
+                    strength: row.strength,
+                    tags,
+                };
+            });
+            return { success: true, output: { results } };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+}
+//# sourceMappingURL=MemorySearchTool.js.map

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

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