@mastra/libsql 1.22.4-alpha.1 → 1.22.5-alpha.0

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-libsql
 description: Documentation for @mastra/libsql. Use when working with @mastra/libsql APIs, configuration, or implementation.
 metadata:
   package: "@mastra/libsql"
-  version: "1.22.4-alpha.1"
+  version: "1.22.5-alpha.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.22.4-alpha.1",
+  "version": "1.22.5-alpha.0",
   "package": "@mastra/libsql",
   "exports": {},
   "modules": {}

package/dist/docs/references/docs-memory-message-history.md

@@ -178,7 +178,7 @@ const agent = mastra.getAgentById('test-agent')
 const memory = await agent.getMemory()
 ```
 
-The `Memory` instance gives you access to functions for listing threads and recalling messages, plus cloning conversations, and more.
+Use the `Memory` instance to query stored threads and messages or clone a conversation.
 
 ## Querying
 

package/dist/docs/references/docs-memory-multi-user-threads.md

@@ -160,7 +160,7 @@ const memory = new Memory({
 
 OM requires a storage adapter that supports it: `@mastra/libsql`, `@mastra/pg`, `@mastra/mongodb`, or `@mastra/oracledb`.
 
-> **Note:** If you switch the Observer to a weaker model and see facts collapse to a generic `User`, use [`observation.instruction`](https://mastra.ai/reference/memory/observational-memory) to teach the Observer how to read the `<turn>` tag.
+> **Note:** If you switch the Observer to a less capable model and see facts attributed to a generic `User` instead of individual participants, use [`observation.instruction`](https://mastra.ai/reference/memory/observational-memory) to explain how to interpret the `<turn>` tag.
 
 ### With working memory
 

package/dist/docs/references/docs-memory-overview.md

@@ -4,7 +4,7 @@
 
 # Memory
 
-Memory enables your agent to remember user messages and agent replies, and tool results across interactions, giving it the context it needs to stay consistent, maintain conversation flow, plus produce better answers over time.
+Memory gives your agent access to earlier messages and tool results. The agent can use this context to answer follow-up questions and recall information from previous interactions.
 
 Mastra agents can be configured to store [message history](https://mastra.ai/docs/memory/message-history). Additionally, you can enable:
 
@@ -153,7 +153,7 @@ To list all threads for a resource, or retrieve a specific thread, [use the memo
 
 ## Observational Memory
 
-For long-running conversations, raw message history grows until it fills the context window, degrading agent performance. [Observational Memory](https://mastra.ai/docs/memory/observational-memory) solves this by running background agents that compress old messages into dense observations, keeping the context window small while preserving long-term memory.
+Long conversations can fill the context window with raw message history and reduce agent performance. [Observational Memory](https://mastra.ai/docs/memory/observational-memory) uses background agents to compress older messages into observations. This reduces the context used by message history while retaining information for later turns.
 
 **For AI agents:** Using Observational Memory requires a storage provider! You either need to set it on the Mastra instance at `src/mastra/index.ts` or pass it to the Agent constructor.
 
@@ -176,7 +176,7 @@ See [Observational Memory](https://mastra.ai/docs/memory/observational-memory) f
 
 ## What the model sees
 
-Each memory feature is added to either the system messages or the conversation messages in the request sent to the model. The layers depend on the features you've enabled. Working memory and semantic recall only appear when configured. The same applies to Observational Memory, while message history is on by default. The diagram shows where each enabled layer is placed in the request. The list below describes what each layer contributes:
+Memory adds context to the system messages or conversation messages sent to the model. Message history is enabled by default. Other memory features contribute context only when configured. The diagram shows where each feature adds its context, and the list below explains what it contributes:
 
 ![Diagram showing how Mastra assembles the model context: system messages containing agent instructions, call-time system messages, working memory, cross-thread semantic recall, and Observational Memory, followed by conversation messages where message history and same-thread semantic recall interleave by timestamp, then call-time context messages, and finally the new user message](/img/memory/memory-context-window-light.svg)
 
@@ -202,7 +202,7 @@ Each delegation creates a fresh `threadId` and a deterministic `resourceId` for
 
 > **Note:** Title generation (`generateTitle`) is a top-level thread concern and **isn't** applied to inherited subagent threads. Because each delegation creates an ephemeral thread that no one sees, running title generation for it would waste an LLM call per delegation. To generate titles for a subagent's own threads, give that subagent its own memory configuration.
 
-The supervisor forwards its conversation context to the subagent so it has enough background to complete the task. Only the delegation prompt and the subagent's response are saved, the full parent conversation isn't stored. You can control which messages reach the subagent with the [`messageFilter`](https://mastra.ai/docs/subagents) callback.
+The supervisor forwards its conversation context to the subagent so it has enough background to complete the task. Only the delegation prompt and the subagent's response are saved; the full parent conversation isn't stored. You can control which messages reach the subagent with the [`messageFilter`](https://mastra.ai/docs/subagents) callback.
 
 > **Note:** Subagent resource IDs are always suffixed with the agent name (`{parentResourceId}-{agentName}`). Different subagents under the same supervisor never share a resource ID through delegation.
 

package/dist/index.cjs

@@ -12,6 +12,84 @@ let crypto$1 = require("crypto");
 let _mastra_core_agent = require("@mastra/core/agent");
 let _mastra_core_evals = require("@mastra/core/evals");
 let _mastra_core_storage_domains_skills = require("@mastra/core/storage/domains/skills");
+//#region src/shared/single-connection-client.ts
+/**
+* Whether `@libsql/client` backs this database with exactly one connection.
+*
+* An in-memory database exists only on the connection that opened it, and each
+* embedded-replica connection carries its own sync state, so `@libsql/client`
+* (>= 0.18.0) gives both a pool of one. Any `execute`/`batch` issued while an
+* interactive `transaction()` holds that connection is rejected immediately
+* with `TRANSACTION_ACTIVE` instead of waiting for the transaction to settle.
+*/
+function isSingleConnectionDatabase({ url, syncUrl }) {
+	return url.includes(":memory:") || Boolean(syncUrl);
+}
+/**
+* Wraps a single-connection client so client calls queue behind open
+* transactions rather than failing with `TRANSACTION_ACTIVE`.
+*
+* `transaction()` takes the gate and releases it when the transaction commits,
+* rolls back, or closes. `execute`, `batch`, `executeMultiple`, and `migrate`
+* wait for the gate to be free before running but do not hold it — the driver
+* executes them synchronously on the connection, so they cannot interleave
+* with each other. Every other member passes through untouched.
+*
+* Callers must not issue client calls from inside their own open transaction
+* (use `tx.execute`); such a call would wait for the transaction it is part of.
+*/
+function gateSingleConnectionClient(client) {
+	let gate = Promise.resolve();
+	const waitForGate = (run) => gate.then(run, run);
+	const transaction = async (mode) => {
+		let release;
+		const held = new Promise((resolve) => {
+			release = resolve;
+		});
+		const previous = gate;
+		gate = previous.then(() => held, () => held);
+		await previous.then(() => void 0, () => void 0);
+		let tx;
+		try {
+			tx = await client.transaction(mode);
+		} catch (error) {
+			release();
+			throw error;
+		}
+		return new Proxy(tx, { get(target, prop) {
+			if (prop === "commit" || prop === "rollback") return async () => {
+				try {
+					await target[prop].call(target);
+				} finally {
+					release();
+				}
+			};
+			if (prop === "close") return () => {
+				try {
+					target.close();
+				} finally {
+					release();
+				}
+			};
+			const value = Reflect.get(target, prop);
+			return typeof value === "function" ? value.bind(target) : value;
+		} });
+	};
+	return new Proxy(client, { get(target, prop) {
+		switch (prop) {
+			case "transaction": return transaction;
+			case "execute":
+			case "batch":
+			case "executeMultiple":
+			case "migrate": return (...args) => waitForGate(() => target[prop].apply(target, args));
+			default: {
+				const value = Reflect.get(target, prop);
+				return typeof value === "function" ? value.bind(target) : value;
+			}
+		}
+	} });
+}
+//#endregion
 //#region src/vector/filter.ts
 /**
 * Translates MongoDB-style filters to LibSQL compatible filters.
@@ -427,13 +505,17 @@ var LibSQLVector = class extends _mastra_core_vector.MastraVector {
 		this.isMemoryDb = url.includes(":memory:");
 		const isLocalDb = (url.startsWith("file:") || this.isMemoryDb) && !syncUrl;
 		const cwd = process.cwd();
-		this.turso = (0, _libsql_client.createClient)({
+		const client = (0, _libsql_client.createClient)({
 			url,
 			syncUrl,
 			authToken,
 			syncInterval,
 			...isLocalDb ? { timeout: 5e3 } : {}
 		});
+		this.turso = isSingleConnectionDatabase({
+			url,
+			syncUrl
+		}) ? gateSingleConnectionClient(client) : client;
 		this.maxRetries = maxRetries;
 		this.initialBackoffMs = initialBackoffMs;
 		if (!Number.isInteger(vectorTopKOverFetchMultiplier) || vectorTopKOverFetchMultiplier < 1) throw new Error("vectorTopKOverFetchMultiplier must be a positive integer");
@@ -1280,24 +1362,26 @@ function transformFromSqlRow({ tableName, sqlRow }) {
 /**
 * Per-client write serialization.
 *
-* `@libsql/client` backs a local (`file:`/`:memory:`) database with a single
-* underlying connection. An interactive `client.transaction('write')` issues a
-* `BEGIN` and then yields to the event loop on every `await tx.execute(...)`.
-* Any autocommit write (`client.execute`/`client.batch`) issued on the same
-* client during that window runs on the same connection — so it is swept into
-* the still-open transaction and is committed or rolled back with it, instead
-* of as its own statement. Two concurrent interactive transactions collide the
-* same way ("cannot start a transaction within a transaction").
+* `@libsql/client` >= 0.18.0 pools connections for local `file:` databases, but
+* SQLite still admits one writer at a time: an interactive
+* `client.transaction('write')` holds `BEGIN` open across every
+* `await tx.execute(...)`, and any other write on the same database in that
+* window contends on the file lock and can fail with `SQLITE_BUSY` once
+* `busy_timeout` expires.
 *
 * This is dormant under the default engine but the evented engine runs many
 * concurrent workflow snapshot writes per agent run, so a write issued by an
-* unrelated domain (e.g. creating a dataset experiment) can silently vanish.
+* unrelated domain (e.g. creating a dataset experiment) can fail spuriously.
 *
 * Serializing every write on a given client closes that window: writes — both
 * autocommit statements and full interactive transactions — run one at a time,
 * so none can interleave with an open transaction. Reads are intentionally not
 * gated; WAL readers never observe a partial write and must not queue behind a
 * long-running writer.
+*
+* `:memory:` databases and embedded replicas get a single pooled connection
+* instead; see `shared/single-connection-client.ts`, which gates *all* calls
+* (reads included) behind open transactions for those clients.
 */
 const clientWriteChains = /* @__PURE__ */ new WeakMap();
 /**
@@ -14222,11 +14306,12 @@ var LibSQLFactoryStorage = class extends _mastra_core_storage.FactoryStorage {
 		super();
 		this.#config = config;
 		const isLocalDb = config.url.startsWith("file:") || config.url.includes(":memory:");
-		this.#client = (0, _libsql_client.createClient)({
+		const client = (0, _libsql_client.createClient)({
 			url: config.url,
 			...config.authToken ? { authToken: config.authToken } : {},
 			...isLocalDb ? { timeout: DEFAULT_CONNECTION_TIMEOUT_MS } : {}
 		});
+		this.#client = isSingleConnectionDatabase(config) ? gateSingleConnectionClient(client) : client;
 		this.ops = new LibSQLFactoryStorageOps(this.#client, this.#schemas, (fn) => withClientWriteLock(this.#client, fn));
 	}
 	getMastraStorage() {
@@ -14384,15 +14469,15 @@ var LibSQLStore = class extends _mastra_core_storage.MastraCompositeStore {
 			mmapSize: config.localPragmas?.mmapSize ?? DEFAULT_LOCAL_MMAP_SIZE
 		};
 		if ("url" in config) {
-			if (config.url.includes(":memory:")) this.shouldCacheInit = false;
 			this.isLocalDb = (config.url.startsWith("file:") || config.url.includes(":memory:")) && !config.syncUrl;
-			this.client = (0, _libsql_client.createClient)({
+			const client = (0, _libsql_client.createClient)({
 				url: config.url,
 				...config.authToken ? { authToken: config.authToken } : {},
 				...config.syncUrl ? { syncUrl: config.syncUrl } : {},
 				...config.syncInterval !== void 0 ? { syncInterval: config.syncInterval } : {},
 				...this.isLocalDb ? { timeout: this.connectionTimeoutMs } : {}
 			});
+			this.client = isSingleConnectionDatabase(config) ? gateSingleConnectionClient(client) : client;
 			this.pragmasReady = this.isLocalDb ? this.applyLocalPragmas() : Promise.resolve();
 		} else {
 			this.client = config.client;