@framers/agentos 0.1.126 → 0.1.128

package/dist/memory/io/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 '../../retrieval/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 used to resolve scoped searches.
+     * @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/io/tools/MemorySearchTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MemorySearchTool.d.ts","sourceRoot":"","sources":["../../../../src/memory/io/tools/MemorySearchTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EACV,KAAK,EACL,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EACjB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sCAAsC,CAAC;AAsBxE;;;;;;;;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,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,mBAAmB,CAAC,kBAAkB,CAAC,CAAC;CAqFpD"}

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

@@ -0,0 +1,185 @@
+/**
+ * @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 { buildNaturalLanguageFtsQuery } from '../../retrieval/store/tracePersistence.js';
+import { resolveMemoryToolScopeId } from './scopeContext.js';
+// ---------------------------------------------------------------------------
+// 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 used to resolve scoped searches.
+     * @returns `{ results }` array on success, or an error result.
+     */
+    async execute(args, context) {
+        try {
+            const rawQuery = args.query.trim();
+            if (!rawQuery) {
+                return { success: true, output: { results: [] } };
+            }
+            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 scopeId = resolveMemoryToolScopeId(args.scope, context);
+                if (scopeId) {
+                    const { dialect } = this.brain.features;
+                    extraClauses.push(`${dialect.jsonExtract('mt.metadata', '$.scopeId')} = ?`);
+                    extraParams.push(scopeId);
+                }
+            }
+            const extraWhere = extraClauses.length > 0 ? `AND ${extraClauses.join(' AND ')}` : '';
+            const { fts } = this.brain.features;
+            const sql = `
+        SELECT mt.id, mt.content, mt.type, mt.scope, mt.strength, mt.tags
+        FROM ${fts.joinClause('memory_traces', 'mt', 'fts', 'memory_traces_fts')}
+        WHERE ${fts.matchClause('memory_traces_fts', '?')}
+          AND mt.deleted = 0
+          ${extraWhere}
+        ORDER BY ${fts.rankExpression('fts')}
+        LIMIT ?
+      `;
+            const runSearch = async (query) => {
+                const params = [query, ...extraParams, limit];
+                return await this.brain.all(sql, params);
+            };
+            let rows;
+            try {
+                rows = await runSearch(rawQuery);
+            }
+            catch (error) {
+                const fallbackQuery = buildNaturalLanguageFtsQuery(rawQuery);
+                if (error?.code !== 'SQLITE_ERROR' || !fallbackQuery || fallbackQuery === rawQuery) {
+                    throw error;
+                }
+                rows = await runSearch(fallbackQuery);
+            }
+            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/io/tools/MemorySearchTool.js.map

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

package/dist/memory/io/tools/MemoryUpdateTool.d.ts

@@ -0,0 +1,92 @@
+/**
+ * @fileoverview MemoryUpdateTool — lets an agent update an existing memory trace.
+ *
+ * Supports partial updates: the agent may change just the content, just the
+ * tags, or both. When the content is changed, the stored embedding is cleared
+ * so the background EmbeddingEncoder will re-embed the trace asynchronously
+ * on the next pass — preventing stale vector data from contaminating semantic
+ * search results.
+ *
+ * @module memory/tools/MemoryUpdateTool
+ */
+import type { ITool, ToolExecutionResult, ToolExecutionContext, JSONSchemaObject } from '../../../core/tools/ITool.js';
+import type { SqliteBrain } from '../../retrieval/store/SqliteBrain.js';
+/**
+ * Input arguments for {@link MemoryUpdateTool}.
+ *
+ * At least one of `content` or `tags` must be provided alongside `traceId`
+ * for an update to have any effect.
+ *
+ * @property traceId - The ID of the memory trace to update (e.g. `mt_1234_0`).
+ * @property content - New text content. When changed, the embedding is cleared.
+ * @property tags    - Replacement tag array (overwrites existing tags entirely).
+ */
+export interface MemoryUpdateInput extends Record<string, any> {
+    traceId: string;
+    content?: string;
+    tags?: string[];
+}
+/**
+ * Output returned by {@link MemoryUpdateTool} on success.
+ *
+ * @property updated - `true` if a matching, non-deleted trace was found and updated.
+ *                     `false` if the trace was not found or was already soft-deleted.
+ */
+export interface MemoryUpdateOutput {
+    updated: boolean;
+}
+/**
+ * ITool implementation that applies partial updates to an existing memory
+ * trace stored in the agent's SQLite brain database.
+ *
+ * **Usage:**
+ * ```ts
+ * const tool = new MemoryUpdateTool(brain);
+ * const result = await tool.execute(
+ *   { traceId: 'mt_1711234567890_0', content: 'Updated content here.' },
+ *   context,
+ * );
+ * // result.output.updated → true
+ * ```
+ */
+export declare class MemoryUpdateTool implements ITool<MemoryUpdateInput, MemoryUpdateOutput> {
+    private readonly brain;
+    /** Globally unique tool identifier. */
+    readonly id = "memory-update-v1";
+    /** LLM-facing tool name. */
+    readonly name = "memory_update";
+    /** Human-readable display name. */
+    readonly displayName = "Update 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);
+    /**
+     * Update a memory trace identified by `traceId`.
+     *
+     * The method builds a dynamic SET clause based on which optional fields
+     * are provided:
+     * - `content` provided → set `content = ?`, also set `embedding = NULL`
+     *   to signal that the cached vector is stale.
+     * - `tags` provided → serialise array as JSON and set `tags = ?`.
+     *
+     * If neither `content` nor `tags` is specified, the method returns
+     * `{ updated: false }` immediately without touching the database.
+     *
+     * A trace that does not exist or has `deleted = 1` returns `{ updated: false }`.
+     *
+     * @param args     - Update input (traceId, optional content/tags).
+     * @param _context - Tool execution context (not used by this tool).
+     * @returns `{ updated }` status, or an error result.
+     */
+    execute(args: MemoryUpdateInput, _context: ToolExecutionContext): Promise<ToolExecutionResult<MemoryUpdateOutput>>;
+}
+//# sourceMappingURL=MemoryUpdateTool.d.ts.map

package/dist/memory/io/tools/MemoryUpdateTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MemoryUpdateTool.d.ts","sourceRoot":"","sources":["../../../../src/memory/io/tools/MemoryUpdateTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACvH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sCAAsC,CAAC;AAOxE;;;;;;;;;GASG;AACH,MAAM,WAAW,iBAAkB,SAAQ,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,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;IA6CvE,OAAO,CAAC,QAAQ,CAAC,KAAK;IA5ClC,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,SAE2E;IAE/F,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,YAAY;IAE7B,wCAAwC;IACxC,QAAQ,CAAC,cAAc,QAAQ;IAE/B,uEAAuE;IACvE,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAkBpC;IAEF;;OAEG;gBAC0B,KAAK,EAAE,WAAW;IAM/C;;;;;;;;;;;;;;;;;OAiBG;IACG,OAAO,CACX,IAAI,EAAE,iBAAiB,EACvB,QAAQ,EAAE,oBAAoB,GAC7B,OAAO,CAAC,mBAAmB,CAAC,kBAAkB,CAAC,CAAC;CAwDpD"}

package/dist/memory/io/tools/MemoryUpdateTool.js

@@ -0,0 +1,136 @@
+/**
+ * @fileoverview MemoryUpdateTool — lets an agent update an existing memory trace.
+ *
+ * Supports partial updates: the agent may change just the content, just the
+ * tags, or both. When the content is changed, the stored embedding is cleared
+ * so the background EmbeddingEncoder will re-embed the trace asynchronously
+ * on the next pass — preventing stale vector data from contaminating semantic
+ * search results.
+ *
+ * @module memory/tools/MemoryUpdateTool
+ */
+import { parseTraceMetadata, sha256Hex } from '../../retrieval/store/tracePersistence.js';
+// ---------------------------------------------------------------------------
+// MemoryUpdateTool
+// ---------------------------------------------------------------------------
+/**
+ * ITool implementation that applies partial updates to an existing memory
+ * trace stored in the agent's SQLite brain database.
+ *
+ * **Usage:**
+ * ```ts
+ * const tool = new MemoryUpdateTool(brain);
+ * const result = await tool.execute(
+ *   { traceId: 'mt_1711234567890_0', content: 'Updated content here.' },
+ *   context,
+ * );
+ * // result.output.updated → true
+ * ```
+ */
+export class MemoryUpdateTool {
+    /**
+     * @param brain - The agent's shared SQLite brain database connection.
+     */
+    constructor(brain) {
+        this.brain = brain;
+        /** Globally unique tool identifier. */
+        this.id = 'memory-update-v1';
+        /** LLM-facing tool name. */
+        this.name = 'memory_update';
+        /** Human-readable display name. */
+        this.displayName = 'Update Memory';
+        /** LLM-facing description. */
+        this.description = 'Update an existing memory trace by ID. You can change the content, the tags, or both. ' +
+            'If content changes, the stored embedding is cleared and will be re-computed automatically.';
+        /** 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 update.',
+                },
+                content: {
+                    type: 'string',
+                    description: 'New text content for the trace. Clears the stored embedding so it can be re-computed.',
+                },
+                tags: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Replacement tag array (overwrites the existing tags entirely).',
+                },
+            },
+            required: ['traceId'],
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // execute
+    // ---------------------------------------------------------------------------
+    /**
+     * Update a memory trace identified by `traceId`.
+     *
+     * The method builds a dynamic SET clause based on which optional fields
+     * are provided:
+     * - `content` provided → set `content = ?`, also set `embedding = NULL`
+     *   to signal that the cached vector is stale.
+     * - `tags` provided → serialise array as JSON and set `tags = ?`.
+     *
+     * If neither `content` nor `tags` is specified, the method returns
+     * `{ updated: false }` immediately without touching the database.
+     *
+     * A trace that does not exist or has `deleted = 1` returns `{ updated: false }`.
+     *
+     * @param args     - Update input (traceId, optional content/tags).
+     * @param _context - Tool execution context (not used by this tool).
+     * @returns `{ updated }` status, or an error result.
+     */
+    async execute(args, _context) {
+        try {
+            const { traceId, content, tags } = args;
+            // Nothing to update — return false without any DB work.
+            if (content === undefined && tags === undefined) {
+                return { success: true, output: { updated: false } };
+            }
+            const current = await this.brain.get(`SELECT content, tags, metadata
+         FROM memory_traces
+         WHERE id = ? AND deleted = 0`, [traceId]);
+            if (!current) {
+                return { success: true, output: { updated: false } };
+            }
+            const nextContent = content ?? current.content;
+            const nextTags = tags !== undefined ? JSON.stringify(tags) : current.tags;
+            const nextMetadataObject = parseTraceMetadata(current.metadata);
+            if (content !== undefined) {
+                nextMetadataObject.content_hash = await sha256Hex(nextContent);
+                delete nextMetadataObject.import_hash;
+            }
+            const nextMetadata = JSON.stringify(nextMetadataObject);
+            const sql = content !== undefined
+                ? `UPDATE memory_traces
+             SET content = ?, tags = ?, metadata = ?, embedding = NULL
+             WHERE id = ? AND deleted = 0`
+                : `UPDATE memory_traces
+             SET content = ?, tags = ?, metadata = ?
+             WHERE id = ? AND deleted = 0`;
+            const changes = await this.brain.transaction(async (trx) => {
+                const info = await trx.run(sql, [nextContent, nextTags, nextMetadata, traceId]);
+                if (info.changes > 0) {
+                    await trx.exec(this.brain.features.fts.rebuildCommand('memory_traces_fts'));
+                }
+                return info.changes;
+            });
+            return { success: true, output: { updated: changes > 0 } };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+}
+//# sourceMappingURL=MemoryUpdateTool.js.map

package/dist/memory/io/tools/MemoryUpdateTool.js.map

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

package/dist/memory/io/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/memory/io/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1E,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEnF,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEnF,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAEhF,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEvG,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,YAAY,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/memory/io/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/memory/io/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAGzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAGzD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAGvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAGzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/memory/io/tools/scopeContext.d.ts

@@ -0,0 +1,11 @@
+import type { ToolExecutionContext } from '../../../core/tools/ITool.js';
+/**
+ * Resolve the effective scope identity for a memory tool call from the active
+ * execution context.
+ *
+ * `user` and `persona` scopes are always resolvable in normal AgentOS tool
+ * execution because `userContext.userId` and `personaId` are required.
+ * `thread` and `organization` additionally rely on optional `sessionData`.
+ */
+export declare function resolveMemoryToolScopeId(scope: string | undefined, context: ToolExecutionContext): string | undefined;
+//# sourceMappingURL=scopeContext.d.ts.map

package/dist/memory/io/tools/scopeContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scopeContext.d.ts","sourceRoot":"","sources":["../../../../src/memory/io/tools/scopeContext.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAezE;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,OAAO,EAAE,oBAAoB,GAC5B,MAAM,GAAG,SAAS,CA8BpB"}

package/dist/memory/io/tools/scopeContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scopeContext.js","sourceRoot":"","sources":["../../../../src/memory/io/tools/scopeContext.ts"],"names":[],"mappings":"AAEA,SAAS,cAAc,CAAC,KAAc;IACpC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,OAAO,OAAO,IAAI,SAAS,CAAC;AAC9B,CAAC;AAED,SAAS,mBAAmB,CAAC,MAAc,EAAE,SAAiB;IAC5D,OAAO,GAAG,MAAM,KAAK,SAAS,EAAE,CAAC;AACnC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,wBAAwB,CACtC,KAAyB,EACzB,OAA6B;IAE7B,MAAM,aAAa,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IAC5C,IAAI,CAAC,aAAa,EAAE,CAAC;QACnB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,MAAM,GAAG,cAAc,CAAC,OAAO,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IAC3D,MAAM,SAAS,GAAG,cAAc,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACpD,MAAM,cAAc,GAClB,cAAc,CAAC,OAAO,CAAC,WAAW,EAAE,cAAc,CAAC;QACnD,cAAc,CAAC,OAAO,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IACjD,MAAM,cAAc,GAClB,cAAc,CAAC,OAAO,CAAC,WAAW,EAAE,cAAc,CAAC;QACnD,cAAc,CAAC,OAAO,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC;IAEtD,QAAQ,aAAa,EAAE,CAAC;QACtB,KAAK,MAAM;YACT,OAAO,MAAM,CAAC;QAChB,KAAK,SAAS;YACZ,IAAI,CAAC,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC;gBAC1B,OAAO,SAAS,CAAC;YACnB,CAAC;YACD,OAAO,mBAAmB,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;QAChD,KAAK,QAAQ;YACX,OAAO,cAAc,CAAC;QACxB,KAAK,cAAc;YACjB,OAAO,cAAc,CAAC;QACxB;YACE,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC"}