@dex-ai/memory 0.3.3 → 0.3.5

package/README.md

@@ -1,36 +1,34 @@
-# @dex-ai/memory-sqlite
+# @dex-ai/memory
 
-SQLite-backed memory Extension for [`@dex-ai/sdk`](https://github.com/klxdev/dex-ai-sdk). Three memory types — **episodic**, **semantic**, **procedural** — in one extension, one SQLite file.
+SQLite-backed memory extension for [`@dex-ai/sdk`](https://github.com/klxdev/dex-ai-sdk). Three memory types — **episodic**, **semantic**, and **procedural** — in one extension and one SQLite file.
 
 ## Install
 
 ```bash
-bun add @dex-ai/memory-sqlite
-# optional: default local embedder (ONNX via Transformers.js)
-bun add @xenova/transformers
+bun add @dex-ai/memory
 ```
 
-`@xenova/transformers` is an optional peer dep. Skip it if you pass your own `embed()` function.
+The default local embedder uses `@xenova/transformers`. Pass your own `embed()` function if you want to use a remote embedding service instead.
 
 ## Usage
 
 ```ts
-import { DexAgent } from '@dex-ai/runtime';
+import { Agent } from '@dex-ai/sdk';
 import { openai } from '@dex-ai/openai';
-import { memoryExtensionSqlite } from '@dex-ai/memory-sqlite';
+import { memoryExtension } from '@dex-ai/memory';
 
-const agent = new DexAgent({
+const agent = await Agent.create({
   provider: openai({ modelId: 'gpt-4.1' }),
   extensions: [
-    memoryExtensionSqlite({
+    memoryExtension({
       path: '~/.dex/memory.db',
       userId: 'alice',
 
       // Optional: a cheaper model for memory's summarize + extract calls.
       llm: { model: 'gpt-4o-mini' },
 
-      // Optional: bring your own embedder (e.g. a remote endpoint).
-      // If omitted, a local Transformers.js embedder (all-MiniLM-L6-v2) is used.
+      // Optional: bring your own embedder, e.g. a remote endpoint.
+      // If omitted, a local Transformers.js embedder is used.
       // embed: async (texts) => await myRemoteEmbedder(texts),
     }),
   ],
@@ -41,44 +39,49 @@ const agent = new DexAgent({
 
 ### Episodic memory — past turns, auto-summarized
 
-Every `generate()` iteration, the extension fires a background task:
+Every `generate()` iteration, the extension can fire a background task:
+
 1. Summarize the turn's new messages into 1-3 sentences via the LLM.
 2. Embed the summary and write both to SQLite.
 
-Background writes are tracked; `agent.dispose()` awaits them.
+Background writes are tracked; `session-stop` awaits them before closing the database.
+
+At recall time (`model-start`), the extension fetches:
 
-At recall time (`onRequest`), the extension fetches:
-- The last **3 most-recent** episodes for the user.
-- The **3 most-similar** episodes via sqlite-vec cosine against the user's last message.
-- De-duplicated by id, sorted newest-first.
+- The last **5 most-recent** episodes for the user by default.
+- The **3 most-similar** episodes via sqlite-vec against the user's last message.
+- De-duplicated results, sorted newest-first.
 
 ### Semantic memory — durable facts
 
 Facts are `(subject, predicate, object)` tuples, unique by `(userId, subject, predicate)`. Written in two ways:
 
-**Automatic extraction** at each iteration stop: the LLM extracts durable claims from the turn and upserts them.
+**Automatic extraction** at each generate stop: the LLM extracts durable claims from the turn and upserts them.
 
 **Model-driven** via tools:
-- `memory.remember_fact({ subject, predicate, object })` — upsert by key.
-- `memory.forget_fact({ subject, predicate })` — delete by key.
 
-At recall time, **all of the user's facts** are injected as a synthetic system message. The set is typically small (tens to low hundreds); if it grows we'll add top-k filtering later.
+- `memory_remember_fact({ subject, predicate, object })` — upsert by key.
+- `memory_forget_fact({ subject, predicate })` — delete by key.
+- `memory_recall_facts({ query, limit? })` — search facts by vector similarity.
+
+At recall time, the most relevant facts for the user's last message are injected as a synthetic memory message.
 
 ### Procedural memory — runbooks
 
 Long-form how-to content. Stored by unique `title`, tagged, with an embedding over `title + body`.
 
 **Tools**:
-- `memory.store_procedure({ title, body, tags? })` — upsert by title.
-- `memory.list_procedures({ query?, tag?, limit? })` — with `query`, returns vector-ranked results; with `tag`, filters; with neither, returns most-recently-updated.
-- `memory.get_procedure({ title })` — fetch full body.
 
-**Auto-inject**: at recall time, the extension does a vector similarity lookup against the user's last message. If the top match scores above the threshold (default 0.5), its full body is prepended to the prompt as a synthetic system message.
+- `memory_store_procedure({ title, body, tags? })` — upsert by title.
+- `memory_list_procedures({ query?, tag?, limit? })` — with `query`, returns vector-ranked results; with `tag`, filters; with neither, returns most-recently-updated.
+- `memory_get_procedure({ title })` — fetch full body by exact title.
+
+**Auto-inject**: at recall time, the extension does a vector similarity lookup against the user's last message. Matching procedure titles are injected; use `memory_get_procedure` to fetch the full runbook when needed.
 
 ## LLM configuration
 
 ```ts
-memoryExtensionSqlite({
+memoryExtension({
   // ...
   llm: {
     provider: customProvider,   // optional — overrides the agent's provider entirely
@@ -90,63 +93,75 @@ memoryExtensionSqlite({
 Resolution rule:
 
 1. If `llm.provider` is set, use it.
-2. Otherwise use the agent's provider (captured from `actx.provider` in `onAgentStart`).
-3. If `llm.model` is set, it's passed via `providerOptions.model` on every memory-internal request. Providers that merge `providerOptions` over the default body — like `@dex-ai/openai` — honor this override per-call. Providers that don't merge `providerOptions` require passing a full `llm.provider` instance.
+2. Otherwise use the agent's model/provider.
+3. If `llm.model` is set, it is passed via `providerOptions.model` on every memory-internal request.
 
 ## Extension options
 
 ```ts
-interface MemoryExtensionSqliteOptions {
+interface MemoryExtensionOptions {
   path: string;                      // SQLite file path or ':memory:'
-  userId: string;                    // owner for episodic + semantic (procedural is global)
+  userId: string;                    // owner for episodic + semantic memory
+
+  vecPath?: string;                  // optional explicit sqlite-vec extension path
+  sqlitePath?: string;               // advanced: override auto-detected Homebrew SQLite dylib
 
   llm?: { provider?: Provider; model?: string };
-  embed?: (texts: string[]) => Promise<number[][]>; // 384-dim
+  embed?: (texts: string[]) => Promise<number[][]>; // 384-dim vectors
 
-  episodicRecent?: number;           // default 3
+  episodicRecent?: number;           // default 5
   episodicSimilar?: number;          // default 3
+  semanticLimit?: number;            // default 10
   proceduralThreshold?: number;      // default 0.5
   autoWrite?: boolean;               // default true; set false to disable auto-summarize+extract
+  autoWriteMinMessages?: number;     // default 2
 }
 ```
 
 ## Injected prompt shape
 
-When memory is available, the extension prepends a single synthetic system message to each provider request. Example:
+When memory is available, the extension inserts a synthetic memory message before the latest user message. Example:
 
-```
+```text
+<memory>
 Recent context:
 - 5m ago: discussed the auth flow; chose JWT over session cookies.
 - 1d ago: debugged a test flake in session-sqlite.
 
-Known facts:
+Relevant facts:
 - user prefers TypeScript
 - project uses PostgreSQL 15
 - user is on macOS
 
-Relevant runbook — deploy-dex (similarity 0.71):
-1. bun run typecheck
-2. bun run test
-3. git tag vX.Y.Z && git push --tags
+Relevant procedures (use memory_get_procedure to fetch details):
+- [deploy-dex] (id: proc_123, similarity: 0.71)
+</memory>
 ```
 
-This message is **not** persisted to `actx.messages` — it's a per-turn rewrite via the `onRequest` reducer, which never mutates the agent's canonical history.
+This message is **not** persisted to `actx.messages` — it is a per-turn rewrite during `model-start`, which never mutates the agent's canonical history.
 
 ## Requirements + gotchas
 
-- **sqlite-vec**: loaded via the `sqlite-vec` npm package (ships prebuilt binaries for macOS, Linux, Windows). Extension construction throws if the binary isn't loadable for your platform.
-- **Transformers.js first-run download**: ~25 MB ONNX model, cached in `~/.cache/huggingface`. Initial `embed()` takes 10-30s; subsequent calls are fast.
-- **Background writes are fire-and-forget.** If the process is killed mid-turn, that turn's memory may not be persisted. `agent.dispose()` awaits in-flight writes normally.
-- **Prompt quality of auto-extraction** depends on the configured model. Cheap models (gpt-4o-mini, Haiku) work but may produce noisier facts. Review with `memory.list_facts` (or just inspect the DB) occasionally and use `memory.forget_fact` to prune.
-- **Procedural is global**, not user-scoped, in v0.1. If you need per-user runbooks, open an issue and we'll add a user_id column.
+- **sqlite-vec**: loaded via the `sqlite-vec` npm package, which ships prebuilt binaries for macOS, Linux, and Windows. Extension construction throws if the binary is not loadable for your platform.
+- **Bun + macOS SQLite**: Bun uses Apple SQLite on macOS by default, and Apple SQLite disables loadable extensions. The extension automatically uses Homebrew SQLite when it exists at `/opt/homebrew/opt/sqlite/lib/libsqlite3.dylib` or `/usr/local/opt/sqlite/lib/libsqlite3.dylib`. If needed, install it and restart Dex:
+
+  ```bash
+  brew install sqlite
+  ```
+
+- **Transformers.js first-run download**: the default local embedder downloads an ONNX model and caches it in `~/.cache/huggingface`. Initial `embed()` may take 10-30s; subsequent calls are faster.
+- **Background writes are fire-and-forget.** If the process is killed mid-turn, that turn's memory may not be persisted. `session-stop` awaits in-flight writes normally.
+- **Prompt quality of auto-extraction** depends on the configured model. Cheap models work but may produce noisier facts. Review with `memory_recall_facts` or inspect the DB, and use `memory_forget_fact` to prune.
+- **Procedural memory is global**, not user-scoped. Episodic and semantic memory are scoped by `userId`.
 
 ## Schema
 
-```
+```text
 episodic         id | user_id | summary | metadata(JSON) | created_at
 episodic_vec     id | embedding(FLOAT[384])       -- sqlite-vec
 
 semantic         id | user_id | subject | predicate | object | source | created_at | updated_at
+semantic_vec     id | embedding(FLOAT[384])       -- sqlite-vec
                  UNIQUE (user_id, subject, predicate)
 
 procedural       id | title(UNIQUE) | body | tags(JSON) | created_at | updated_at
@@ -161,4 +176,6 @@ _schema_migrations  name(PK) | applied_at
 bun test
 ```
 
-33 tests as of v0.1: schema/migrations, each memory type's read/write path, LLM helpers, and two end-to-end tests that exercise the full Agent + Extension flow.
+On macOS, install/configure Homebrew SQLite first if you see `This build of sqlite3 does not support dynamic extension loading`.
+
+The test suite covers schema/migrations, each memory type's read/write path, LLM helpers, and end-to-end Agent + extension flow.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dex-ai/memory",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "SQLite-backed memory Extension for @dex-ai/sdk — episodic, semantic, and procedural memory in one package.",
   "type": "module",
   "exports": {
@@ -32,7 +32,6 @@
     "@types/bun": "latest",
     "bun-types": "latest",
     "zod": "^3.23.8",
-    "@xenova/transformers": "^2.17.2",
     "@changesets/cli": "^2.29.0"
   },
   "sideEffects": false,

package/src/db.test.ts

@@ -1,4 +1,6 @@
+import { Database } from 'bun:sqlite';
 import { describe, expect, test } from 'bun:test';
+import { fileURLToPath } from 'node:url';
 import { MemoryDb, EMBED_DIMS } from './db';
 
 describe('MemoryDb', () => {
@@ -40,6 +42,16 @@ describe('MemoryDb', () => {
     }
   });
 
+  test('tolerates SQLite being loaded before custom sqlite configuration', () => {
+    const alreadyOpen = new Database(':memory:');
+    try {
+      const db = new MemoryDb({ path: ':memory:', sqlitePath: fileURLToPath(import.meta.url) });
+      db.close();
+    } finally {
+      alreadyOpen.close();
+    }
+  });
+
   test('EMBED_DIMS is 384', () => {
     expect(EMBED_DIMS).toBe(384);
   });

package/src/db.ts

@@ -9,30 +9,35 @@
  * platform), we throw a descriptive error at construction time so apps see it
  * immediately rather than on first recall.
  */
-import { Database } from 'bun:sqlite';
-import * as sqliteVec from 'sqlite-vec';
-import { existsSync, mkdirSync, copyFileSync } from 'node:fs';
-import { join, dirname } from 'node:path';
-import { tmpdir } from 'node:os';
+import { Database } from "bun:sqlite";
+import * as sqliteVec from "sqlite-vec";
+import { existsSync } from "node:fs";
+import { platform } from "node:process";
 
 /** Embedding dimensions — matches Xenova/all-MiniLM-L6-v2. */
 export const EMBED_DIMS = 384;
 
 export interface OpenDbOptions {
-  /** Absolute path to the DB file, or ':memory:'. Created if missing. */
-  path: string;
-  /**
-   * Optional path to the sqlite-vec loadable extension (vec0.so / vec0.dylib).
-   * When running inside a compiled binary, the normal require.resolve() won't
-   * find the .so — pass the extracted path here instead.
-   */
-  vecPath?: string;
+	/** Absolute path to the DB file, or ':memory:'. Created if missing. */
+	path: string;
+	/**
+	 * Optional path to the sqlite-vec loadable extension (vec0.so / vec0.dylib).
+	 * When running inside a compiled binary, the normal require.resolve() won't
+	 * find the .so — pass the extracted path here instead.
+	 */
+	vecPath?: string;
+	/**
+	 * Optional path to a SQLite dynamic library with extension loading enabled.
+	 * On macOS, Bun defaults to Apple SQLite, which disables loadable extensions.
+	 * Pass a Homebrew SQLite dylib path here, or set DEX_SQLITE_DYLIB.
+	 */
+	sqlitePath?: string;
 }
 
 const MIGRATIONS: Array<{ name: string; sql: string }> = [
-  {
-    name: '001_init',
-    sql: `
+	{
+		name: "001_init",
+		sql: `
       CREATE TABLE IF NOT EXISTS episodic (
         id         TEXT PRIMARY KEY,
         user_id    TEXT NOT NULL,
@@ -65,11 +70,11 @@ const MIGRATIONS: Array<{ name: string; sql: string }> = [
       );
       CREATE INDEX IF NOT EXISTS idx_procedural_title ON procedural(title);
     `,
-  },
-  {
-    name: '002_vec',
-    // vec0 virtual tables. Must run AFTER sqlite-vec is loaded.
-    sql: `
+	},
+	{
+		name: "002_vec",
+		// vec0 virtual tables. Must run AFTER sqlite-vec is loaded.
+		sql: `
       CREATE VIRTUAL TABLE IF NOT EXISTS episodic_vec USING vec0(
         id TEXT PRIMARY KEY,
         embedding FLOAT[${EMBED_DIMS}]
@@ -79,71 +84,134 @@ const MIGRATIONS: Array<{ name: string; sql: string }> = [
         embedding FLOAT[${EMBED_DIMS}]
       );
     `,
-  },
-  {
-    name: '003_semantic_vec',
-    sql: `
+	},
+	{
+		name: "003_semantic_vec",
+		sql: `
       CREATE VIRTUAL TABLE IF NOT EXISTS semantic_vec USING vec0(
         id TEXT PRIMARY KEY,
         embedding FLOAT[${EMBED_DIMS}]
       );
     `,
-  },
+	},
 ];
 
+const PACKAGE_NAME = "@dex-ai/memory";
+const SQLITE_DYLIB_ENV = "DEX_SQLITE_DYLIB";
+
+const HOMEBREW_SQLITE_DYLIBS = [
+	"/opt/homebrew/opt/sqlite/lib/libsqlite3.dylib",
+	"/usr/local/opt/sqlite/lib/libsqlite3.dylib",
+];
+
+let customSqliteConfigured = false;
+let customSqliteAttempted = false;
+
+function isSQLiteAlreadyLoadedError(err: unknown): boolean {
+	return err instanceof Error && /SQLite already loaded/i.test(err.message);
+}
+
+function configureCustomSQLite(sqlitePath?: string): void {
+	if (customSqliteConfigured || platform !== "darwin") return;
+	if (sqlitePath === undefined && customSqliteAttempted) return;
+	customSqliteAttempted = true;
+
+	const candidate =
+		sqlitePath ??
+		Bun.env[SQLITE_DYLIB_ENV] ??
+		HOMEBREW_SQLITE_DYLIBS.find(existsSync);
+	if (candidate === undefined) return;
+
+	if (!existsSync(candidate)) {
+		throw new Error(
+			`${PACKAGE_NAME}: configured SQLite dylib does not exist: ${candidate}`,
+		);
+	}
+
+	try {
+		if (!Database.setCustomSQLite(candidate)) {
+			throw new Error(`failed to configure custom SQLite dylib: ${candidate}`);
+		}
+		customSqliteConfigured = true;
+	} catch (err) {
+		// Bun only allows setCustomSQLite() before SQLite is loaded anywhere in
+		// the process. Dex may load another SQLite-backed extension first. In
+		// that case, keep using the already-loaded SQLite and let sqlite-vec
+		// loading below determine whether the current build supports extensions.
+		if (isSQLiteAlreadyLoadedError(err)) return;
+		throw new Error(
+			`${PACKAGE_NAME}: ${err instanceof Error ? err.message : String(err)}`,
+		);
+	}
+}
+
+function customSQLiteHelp(): string {
+	if (platform !== "darwin") return "";
+	return " On macOS, Bun uses Apple SQLite by default, which disables loadable extensions. Install SQLite with `brew install sqlite`, then restart Dex.";
+}
+
+// Configure Bun to use Homebrew SQLite as soon as this module is imported.
+// Users should only need to install SQLite; no environment variables are
+// required for the common Homebrew locations.
+configureCustomSQLite();
+
 function applyMigrations(db: Database): void {
-  db.exec(`
+	db.exec(`
     CREATE TABLE IF NOT EXISTS _schema_migrations (
       name       TEXT PRIMARY KEY,
       applied_at INTEGER NOT NULL
     );
   `);
-  const already = new Set(
-    db
-      .prepare('SELECT name FROM _schema_migrations')
-      .all()
-      .map((r) => (r as { name: string }).name),
-  );
-  const record = db.prepare('INSERT INTO _schema_migrations(name, applied_at) VALUES(?, ?)');
-  for (const m of MIGRATIONS) {
-    if (already.has(m.name)) continue;
-    db.transaction(() => {
-      db.exec(m.sql);
-      record.run(m.name, Date.now());
-    })();
-  }
+	const already = new Set(
+		db
+			.prepare("SELECT name FROM _schema_migrations")
+			.all()
+			.map((r) => (r as { name: string }).name),
+	);
+	const record = db.prepare(
+		"INSERT INTO _schema_migrations(name, applied_at) VALUES(?, ?)",
+	);
+	for (const m of MIGRATIONS) {
+		if (already.has(m.name)) continue;
+		db.transaction(() => {
+			db.exec(m.sql);
+			record.run(m.name, Date.now());
+		})();
+	}
 }
 
 export class MemoryDb {
-  readonly db: Database;
-
-  constructor(opts: OpenDbOptions) {
-    this.db = new Database(opts.path, { create: true });
-    this.db.exec('PRAGMA journal_mode = WAL; PRAGMA foreign_keys = ON;');
-
-    // Load sqlite-vec. Failure here is fatal — no point constructing the
-    // extension if vector tables won't work.
-    try {
-      if (opts.vecPath) {
-        // Compiled binary mode: load from explicit path
-        this.db.loadExtension(opts.vecPath);
-      } else {
-        // Normal mode: sqlite-vec resolves the platform-specific .so via require.resolve()
-        (sqliteVec as { load: (db: unknown) => void }).load(this.db);
-      }
-    } catch (err) {
-      this.db.close();
-      throw new Error(
-        `@dex-ai/memory-sqlite: failed to load sqlite-vec extension. ` +
-          `Ensure the sqlite-vec npm package's prebuilt binary is available for this platform. ` +
-          `Original error: ${err instanceof Error ? err.message : String(err)}`,
-      );
-    }
+	readonly db: Database;
+
+	constructor(opts: OpenDbOptions) {
+		configureCustomSQLite(opts.sqlitePath);
+		this.db = new Database(opts.path, { create: true });
+		this.db.exec("PRAGMA journal_mode = WAL; PRAGMA foreign_keys = ON;");
+
+		// Load sqlite-vec. Failure here is fatal — no point constructing the
+		// extension if vector tables won't work.
+		try {
+			if (opts.vecPath) {
+				// Compiled binary mode: load from explicit path
+				this.db.loadExtension(opts.vecPath);
+			} else {
+				// Normal mode: sqlite-vec resolves the platform-specific .so via require.resolve()
+				(sqliteVec as { load: (db: unknown) => void }).load(this.db);
+			}
+		} catch (err) {
+			this.db.close();
+			throw new Error(
+				`${PACKAGE_NAME}: failed to load sqlite-vec extension. ` +
+					`Ensure the sqlite-vec npm package's prebuilt binary is available for this platform.` +
+					customSQLiteHelp() +
+					` Original error: ${err instanceof Error ? err.message : String(err)}`,
+			);
+		}
 
-    applyMigrations(this.db);
-  }
+		applyMigrations(this.db);
+	}
 
-  close(): void {
-    this.db.close();
-  }
+	close(): void {
+		this.db.close();
+	}
 }

package/src/extension.ts

@@ -57,6 +57,12 @@ export interface MemoryExtensionOptions {
 	 * cannot locate the platform package.
 	 */
 	vecPath?: string;
+	/**
+	 * Explicit path to a SQLite dynamic library with extension loading enabled.
+	 * Useful on macOS, where Bun defaults to Apple SQLite, which disables
+	 * loadable extensions. Can also be configured with DEX_SQLITE_DYLIB.
+	 */
+	sqlitePath?: string;
 
 	/**
 	 * LLM override for summarization + fact extraction.
@@ -365,6 +371,9 @@ export function memoryExtension(
 				...(resolvedOpts.vecPath !== undefined
 					? { vecPath: resolvedOpts.vecPath }
 					: {}),
+				...(resolvedOpts.sqlitePath !== undefined
+					? { sqlitePath: resolvedOpts.sqlitePath }
+					: {}),
 			});
 			const episodic = new EpisodicStore(db.db);
 			const semantic = new SemanticStore(db.db);

package/src/index.ts

@@ -1,5 +1,5 @@
 /**
- * @dex-ai/memory-sqlite — SQLite-backed memory Extension for Dex.
+ * @dex-ai/memory — SQLite-backed memory Extension for Dex.
  *
  * Three memory types in one extension, one SQLite file:
  *   - Episodic:   summarized past turns, recalled by recency + similarity.
@@ -10,7 +10,7 @@
  *
  *   import { Agent } from '@dex-ai/sdk';
  *   import { openai } from '@dex-ai/openai';
- *   import { memoryExtension } from '@dex-ai/memory-sqlite';
+ *   import { memoryExtension } from '@dex-ai/memory';
  *
  *   const agent = await Agent.create({
  *     provider: openai({ modelId: 'gpt-4.1' }),
@@ -23,10 +23,10 @@
  *     ],
  *   });
  */
-export { memoryExtension } from './extension';
-export type { MemoryExtensionOptions } from './extension';
+export { memoryExtension } from "./extension";
+export type { MemoryExtensionOptions } from "./extension";
 
-export { localEmbedder } from './embedder';
-export type { Embedder } from './embedder';
+export { localEmbedder } from "./embedder";
+export type { Embedder } from "./embedder";
 
-export type { MemoryLlmOptions } from './summarize';
+export type { MemoryLlmOptions } from "./summarize";

package/src/tools.ts

@@ -5,8 +5,7 @@
  * Tools are namespaced `memory_<name>` so they don't collide with other
  * extensions' tool names.
  */
-import type { Tool, ToolOutput } from "@dex-ai/sdk";
-import { z } from "zod";
+import { Schema, type Tool, type ToolOutput } from "@dex-ai/sdk";
 import type { Embedder } from "./embedder";
 import type { SemanticStore } from "./semantic";
 import type { ProceduralStore } from "./procedural";
@@ -16,6 +15,13 @@ function err(msg: string): ToolOutput {
 	return { type: "error-text", value: msg };
 }
 
+type RecallFactsInput = { query: string; limit?: number };
+type RememberFactInput = { subject: string; predicate: string; object: string };
+type ForgetFactInput = { subject: string; predicate: string };
+type ListProceduresInput = { query?: string; tag?: string; limit?: number };
+type GetProcedureInput = { title: string };
+type StoreProcedureInput = { title: string; body: string; tags?: string[] };
+
 /* ------------------------------------------------------------------ */
 /* Semantic tools                                                      */
 /* ------------------------------------------------------------------ */
@@ -24,19 +30,23 @@ export function recallFactsTool(
 	store: SemanticStore,
 	userId: string,
 	embed: Embedder,
-): Tool {
-	const schema = z.object({
-		query: z
-			.string()
-			.min(1)
-			.describe("Free-text query to search for relevant facts by similarity."),
-		limit: z
-			.number()
-			.int()
-			.positive()
-			.max(50)
-			.optional()
-			.describe("Max results. Default 20."),
+): Tool<RecallFactsInput> {
+	const schema = Schema.fromJsonSchema<RecallFactsInput>({
+		type: "object",
+		properties: {
+			query: {
+				type: "string",
+				minLength: 1,
+				description: "Free-text query to search for relevant facts by similarity.",
+			},
+			limit: {
+				type: "integer",
+				minimum: 1,
+				maximum: 50,
+				description: "Max results. Default 20.",
+			},
+		},
+		required: ["query"],
 	});
 	return {
 		name: "memory_recall_facts",
@@ -46,7 +56,7 @@ export function recallFactsTool(
 			"Search long-term semantic memory for facts relevant to a query. Returns the top matching facts by vector similarity. Use this to look up specific knowledge about the user, project, or environment.",
 		parameters: schema,
 		async execute(input): Promise<ToolOutput> {
-			const parsed = schema.parse(input);
+			const parsed = input;
 			const limit = parsed.limit ?? 20;
 			try {
 				const [vec] = await embed([parsed.query]);
@@ -77,17 +87,27 @@ export function rememberFactTool(
 	store: SemanticStore,
 	userId: string,
 	embed: Embedder,
-): Tool {
-	const schema = z.object({
-		subject: z
-			.string()
-			.min(1)
-			.describe("Subject of the fact, e.g. 'user', 'project'."),
-		predicate: z
-			.string()
-			.min(1)
-			.describe("Predicate linking subject to object, e.g. 'prefers', 'uses'."),
-		object: z.string().min(1).describe("The value of the claim."),
+): Tool<RememberFactInput> {
+	const schema = Schema.fromJsonSchema<RememberFactInput>({
+		type: "object",
+		properties: {
+			subject: {
+				type: "string",
+				minLength: 1,
+				description: "Subject of the fact, e.g. 'user', 'project'.",
+			},
+			predicate: {
+				type: "string",
+				minLength: 1,
+				description: "Predicate linking subject to object, e.g. 'prefers', 'uses'.",
+			},
+			object: {
+				type: "string",
+				minLength: 1,
+				description: "The value of the claim.",
+			},
+		},
+		required: ["subject", "predicate", "object"],
 	});
 	return {
 		name: "memory_remember_fact",
@@ -97,7 +117,7 @@ export function rememberFactTool(
 			"Store a durable fact (subject, predicate, object) in long-term semantic memory. Upsert by (subject, predicate); the latest object replaces any prior one.",
 		parameters: schema,
 		async execute(input): Promise<ToolOutput> {
-			const parsed = schema.parse(input);
+			const parsed = input;
 			try {
 				const factText = `${parsed.subject} ${parsed.predicate} ${parsed.object}`;
 				const [vec] = await embed([factText]);
@@ -119,10 +139,17 @@ export function rememberFactTool(
 	};
 }
 
-export function forgetFactTool(store: SemanticStore, userId: string): Tool {
-	const schema = z.object({
-		subject: z.string().min(1),
-		predicate: z.string().min(1),
+export function forgetFactTool(
+	store: SemanticStore,
+	userId: string,
+): Tool<ForgetFactInput> {
+	const schema = Schema.fromJsonSchema<ForgetFactInput>({
+		type: "object",
+		properties: {
+			subject: { type: "string", minLength: 1 },
+			predicate: { type: "string", minLength: 1 },
+		},
+		required: ["subject", "predicate"],
 	});
 	return {
 		name: "memory_forget_fact",
@@ -132,7 +159,7 @@ export function forgetFactTool(store: SemanticStore, userId: string): Tool {
 			"Delete a stored semantic fact by (subject, predicate). Returns { deleted: boolean }.",
 		parameters: schema,
 		async execute(input): Promise<ToolOutput> {
-			const parsed = schema.parse(input);
+			const parsed = input;
 			const res = await store.delete({
 				userId,
 				subject: parsed.subject,
@@ -150,23 +177,25 @@ export function forgetFactTool(store: SemanticStore, userId: string): Tool {
 export function listProceduresTool(
 	store: ProceduralStore,
 	embed: Embedder,
-): Tool {
-	const schema = z.object({
-		query: z
-			.string()
-			.optional()
-			.describe("Free-text task to search by similarity."),
-		tag: z
-			.string()
-			.optional()
-			.describe("Filter to procedures tagged with this string."),
-		limit: z
-			.number()
-			.int()
-			.positive()
-			.max(50)
-			.optional()
-			.describe("Max results. Default 10."),
+): Tool<ListProceduresInput> {
+	const schema = Schema.fromJsonSchema<ListProceduresInput>({
+		type: "object",
+		properties: {
+			query: {
+				type: "string",
+				description: "Free-text task to search by similarity.",
+			},
+			tag: {
+				type: "string",
+				description: "Filter to procedures tagged with this string.",
+			},
+			limit: {
+				type: "integer",
+				minimum: 1,
+				maximum: 50,
+				description: "Max results. Default 10.",
+			},
+		},
 	});
 	return {
 		name: "memory_list_procedures",
@@ -176,7 +205,7 @@ export function listProceduresTool(
 			"List runbooks/procedures. With `query`, returns vector-similarity-ranked results. With `tag`, filters by tag. With neither, returns most-recent.",
 		parameters: schema,
 		async execute(input): Promise<ToolOutput> {
-			const parsed = schema.parse(input);
+			const parsed = input;
 			const limit = parsed.limit ?? 10;
 			try {
 				if (parsed.query !== undefined && parsed.query.trim() !== "") {
@@ -201,9 +230,17 @@ export function listProceduresTool(
 	};
 }
 
-export function getProcedureTool(store: ProceduralStore): Tool {
-	const schema = z.object({
-		title: z.string().min(1).describe("Exact title of the procedure to fetch."),
+export function getProcedureTool(store: ProceduralStore): Tool<GetProcedureInput> {
+	const schema = Schema.fromJsonSchema<GetProcedureInput>({
+		type: "object",
+		properties: {
+			title: {
+				type: "string",
+				minLength: 1,
+				description: "Exact title of the procedure to fetch.",
+			},
+		},
+		required: ["title"],
 	});
 	return {
 		name: "memory_get_procedure",
@@ -213,7 +250,7 @@ export function getProcedureTool(store: ProceduralStore): Tool {
 			"Fetch a procedure by title. Returns the full body and tags, or null.",
 		parameters: schema,
 		async execute(input): Promise<ToolOutput> {
-			const parsed = schema.parse(input);
+			const parsed = input;
 			const row = await store.getByTitle(parsed.title);
 			return { type: "json", value: row };
 		},
@@ -223,14 +260,27 @@ export function getProcedureTool(store: ProceduralStore): Tool {
 export function storeProcedureTool(
 	store: ProceduralStore,
 	embed: Embedder,
-): Tool {
-	const schema = z.object({
-		title: z.string().min(1).describe("Unique title of the runbook."),
-		body: z
-			.string()
-			.min(1)
-			.describe("The runbook contents, typically markdown."),
-		tags: z.array(z.string()).optional().describe("Tags for filtering."),
+): Tool<StoreProcedureInput> {
+	const schema = Schema.fromJsonSchema<StoreProcedureInput>({
+		type: "object",
+		properties: {
+			title: {
+				type: "string",
+				minLength: 1,
+				description: "Unique title of the runbook.",
+			},
+			body: {
+				type: "string",
+				minLength: 1,
+				description: "The runbook contents, typically markdown.",
+			},
+			tags: {
+				type: "array",
+				items: { type: "string" },
+				description: "Tags for filtering.",
+			},
+		},
+		required: ["title", "body"],
 	});
 	return {
 		name: "memory_store_procedure",
@@ -240,7 +290,7 @@ export function storeProcedureTool(
 			"Upsert a runbook by title. Overwrites body+tags for an existing title. Vector embedding is computed from title and body automatically.",
 		parameters: schema,
 		async execute(input): Promise<ToolOutput> {
-			const parsed = schema.parse(input);
+			const parsed = input;
 			try {
 				const [vec] = await embed([`${parsed.title}\n\n${parsed.body}`]);
 				if (vec === undefined) return err("embedder returned no vector");