@framers/agentos 0.1.101 → 0.1.103

package/dist/memory/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 '../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/tools/MemoryUpdateTool.d.ts.map

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

package/dist/memory/tools/MemoryUpdateTool.js

@@ -0,0 +1,125 @@
+/**
+ * @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
+ */
+// ---------------------------------------------------------------------------
+// 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 } };
+            }
+            // Build the SET clause dynamically.
+            const setClauses = [];
+            const params = [];
+            if (content !== undefined) {
+                // Changing content invalidates the stored embedding vector.
+                setClauses.push('content = ?', 'embedding = NULL');
+                params.push(content);
+            }
+            if (tags !== undefined) {
+                setClauses.push('tags = ?');
+                params.push(JSON.stringify(tags));
+            }
+            // WHERE clause: only update active (non-deleted) traces.
+            params.push(traceId);
+            const sql = `UPDATE memory_traces SET ${setClauses.join(', ')} WHERE id = ? AND deleted = 0`;
+            // better-sqlite3 `.run()` accepts rest parameters; cast via unknown[] for TS.
+            const info = this.brain.db.prepare(sql).run(...params);
+            const changes = 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/tools/MemoryUpdateTool.js.map

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

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

@@ -0,0 +1,32 @@
+/**
+ * @fileoverview Barrel exports for the agent memory editor tools.
+ *
+ * These tools expose a self-management API that lets AgentOS agents
+ * read, write, search, and consolidate their own long-term memory traces.
+ *
+ * ## Available tools
+ *
+ * | Tool class           | Tool name         | Description                                |
+ * |----------------------|-------------------|--------------------------------------------|
+ * | {@link MemoryAddTool}    | `memory_add`      | Store a new memory trace                   |
+ * | {@link MemoryUpdateTool} | `memory_update`   | Update content or tags of an existing trace|
+ * | {@link MemoryDeleteTool} | `memory_delete`   | Soft-delete a trace by ID                  |
+ * | {@link MemoryMergeTool}  | `memory_merge`    | Merge multiple traces into one             |
+ * | {@link MemorySearchTool} | `memory_search`   | FTS5 full-text search over traces          |
+ * | {@link MemoryReflectTool}| `memory_reflect`  | Trigger offline consolidation cycle        |
+ *
+ * @module memory/tools
+ */
+export { MemoryAddTool } from './MemoryAddTool.js';
+export type { MemoryAddInput, MemoryAddOutput } from './MemoryAddTool.js';
+export { MemoryUpdateTool } from './MemoryUpdateTool.js';
+export type { MemoryUpdateInput, MemoryUpdateOutput } from './MemoryUpdateTool.js';
+export { MemoryDeleteTool } from './MemoryDeleteTool.js';
+export type { MemoryDeleteInput, MemoryDeleteOutput } from './MemoryDeleteTool.js';
+export { MemoryMergeTool } from './MemoryMergeTool.js';
+export type { MemoryMergeInput, MemoryMergeOutput } from './MemoryMergeTool.js';
+export { MemorySearchTool } from './MemorySearchTool.js';
+export type { MemorySearchInput, MemorySearchOutput, MemorySearchResult } from './MemorySearchTool.js';
+export { MemoryReflectTool } from './MemoryReflectTool.js';
+export type { MemoryReflectInput } from './MemoryReflectTool.js';
+//# sourceMappingURL=index.d.ts.map

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

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

@@ -0,0 +1,26 @@
+/**
+ * @fileoverview Barrel exports for the agent memory editor tools.
+ *
+ * These tools expose a self-management API that lets AgentOS agents
+ * read, write, search, and consolidate their own long-term memory traces.
+ *
+ * ## Available tools
+ *
+ * | Tool class           | Tool name         | Description                                |
+ * |----------------------|-------------------|--------------------------------------------|
+ * | {@link MemoryAddTool}    | `memory_add`      | Store a new memory trace                   |
+ * | {@link MemoryUpdateTool} | `memory_update`   | Update content or tags of an existing trace|
+ * | {@link MemoryDeleteTool} | `memory_delete`   | Soft-delete a trace by ID                  |
+ * | {@link MemoryMergeTool}  | `memory_merge`    | Merge multiple traces into one             |
+ * | {@link MemorySearchTool} | `memory_search`   | FTS5 full-text search over traces          |
+ * | {@link MemoryReflectTool}| `memory_reflect`  | Trigger offline consolidation cycle        |
+ *
+ * @module memory/tools
+ */
+export { MemoryAddTool } from './MemoryAddTool.js';
+export { MemoryUpdateTool } from './MemoryUpdateTool.js';
+export { MemoryDeleteTool } from './MemoryDeleteTool.js';
+export { MemoryMergeTool } from './MemoryMergeTool.js';
+export { MemorySearchTool } from './MemorySearchTool.js';
+export { MemoryReflectTool } from './MemoryReflectTool.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/memory/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@framers/agentos",
-  "version": "0.1.101",
+  "version": "0.1.103",
   "description": "Modular AgentOS orchestration library",
   "type": "module",
   "main": "dist/index.js",
@@ -204,6 +204,7 @@
     "@semantic-release/github": "^9.2.4",
     "@semantic-release/npm": "^12.0.1",
     "@semantic-release/release-notes-generator": "^14.0.1",
+    "@types/better-sqlite3": "^7.6.13",
     "@types/natural": "^5.1.5",
     "@types/node": "^20.12.12",
     "conventional-changelog-conventionalcommits": "^7.0.2",
@@ -228,10 +229,14 @@
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "axios": "^1.7.7",
+    "gray-matter": "^4.0.3",
     "lru-cache": "^11.1.0",
+    "mammoth": "^1.12.0",
+    "minimatch": "^9.0.5",
     "natural": "^6.12.0",
     "openredaction": "^1.1.2",
     "pino": "^9.14.0",
+    "unpdf": "^1.4.0",
     "uuid": "^11.1.0",
     "yaml": "^2.8.1",
     "zod": "^4.3.6"