getmnemo-vercel-ai 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mnemo, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# @ledgermem/vercel-ai
+
+LedgerMem adapter for the [Vercel AI SDK](https://sdk.vercel.dev). Drop-in
+`tool()` definitions that let any model search and write persistent memory,
+plus a small React hook for client-side memory views.
+
+## Install
+
+```bash
+npm install @ledgermem/vercel-ai @ledgermem/memory ai
+```
+
+Set `LEDGERMEM_API_KEY` and `LEDGERMEM_WORKSPACE_ID` in your environment, or
+pass them explicitly.
+
+## Quickstart (30 seconds)
+
+```ts
+import { streamText } from "ai";
+import { openai } from "@ai-sdk/openai";
+import { ledgermemTools } from "@ledgermem/vercel-ai";
+
+const result = await streamText({
+  model: openai("gpt-4o"),
+  tools: ledgermemTools, // memorySearch + memoryAdd
+  maxSteps: 5,
+  messages: [{ role: "user", content: "What did I tell you about my coffee?" }],
+});
+
+for await (const chunk of result.textStream) process.stdout.write(chunk);
+```
+
+## Per-user memory (route handler)
+
+```ts
+import { createLedgerMemTools } from "@ledgermem/vercel-ai";
+
+export async function POST(req: Request) {
+  const { messages, userId } = await req.json();
+  const tools = createLedgerMemTools({ metadata: { userId } });
+  return streamText({ model: openai("gpt-4o"), tools, messages }).toDataStreamResponse();
+}
+```
+
+## React hook
+
+```tsx
+"use client";
+import { useLedgerMem } from "@ledgermem/vercel-ai/react";
+
+export function MemorySidebar() {
+  const { results, search, loading } = useLedgerMem({ initialQuery: "preferences" });
+  return (
+    <ul>
+      {results.map((m: any) => <li key={m.id}>{m.content}</li>)}
+    </ul>
+  );
+}
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { createMnemoTools, getmnemoTools, type MnemoToolsOptions, type MnemoToolset, } from "./tools.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,KAAK,iBAAiB,EACtB,KAAK,YAAY,GAClB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { createMnemoTools, getmnemoTools, } from "./tools.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,aAAa,GAGd,MAAM,YAAY,CAAC"}

package/dist/react.d.ts

@@ -0,0 +1,25 @@
+import { Mnemo } from "getmnemo";
+export interface UseMnemoOptions {
+    apiKey?: string;
+    workspaceId?: string;
+    client?: Mnemo;
+    /** Initial query to run on mount; pass `undefined` to skip. */
+    initialQuery?: string;
+    initialLimit?: number;
+}
+export interface UseMnemoResult<T = unknown> {
+    results: T[];
+    loading: boolean;
+    error: Error | null;
+    search: (query: string, limit?: number) => Promise<T[]>;
+    add: (content: string, metadata?: Record<string, unknown>) => Promise<T>;
+    remove: (id: string) => Promise<void>;
+}
+/**
+ * Tiny React hook for direct Mnemo access from client components.
+ *
+ * For tool-use inside `useChat`, prefer wiring `getmnemoTools` into the
+ * server route instead — this hook is for sidebars / memory inspectors.
+ */
+export declare function useMnemo<T = unknown>(options?: UseMnemoOptions): UseMnemoResult<T>;
+//# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAEjC,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,KAAK,CAAC;IACf,+DAA+D;IAC/D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,OAAO;IACzC,OAAO,EAAE,CAAC,EAAE,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IACxD,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IACzE,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,CAAC,GAAG,OAAO,EAClC,OAAO,GAAE,eAAoB,GAC5B,cAAc,CAAC,CAAC,CAAC,CAsFnB"}

package/dist/react.js

@@ -0,0 +1,92 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { Mnemo } from "getmnemo";
+/**
+ * Tiny React hook for direct Mnemo access from client components.
+ *
+ * For tool-use inside `useChat`, prefer wiring `getmnemoTools` into the
+ * server route instead — this hook is for sidebars / memory inspectors.
+ */
+export function useMnemo(options = {}) {
+    const [client] = useState(() => resolveClient(options));
+    const [results, setResults] = useState([]);
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState(null);
+    // Last-wins guard: every search() bumps the counter and only the most
+    // recent call is allowed to write to state. Without this, two rapid
+    // searches let the slower one overwrite the fresher one (the classic
+    // "stale request wins" race), and unmounting mid-flight wrote state on
+    // a torn-down component.
+    const requestIdRef = useRef(0);
+    const mountedRef = useRef(true);
+    useEffect(() => {
+        mountedRef.current = true;
+        return () => {
+            mountedRef.current = false;
+        };
+    }, []);
+    const search = useCallback(async (query, limit = 5) => {
+        const myId = ++requestIdRef.current;
+        setLoading(true);
+        setError(null);
+        try {
+            const r = ((await client.search({ query, limit })).hits);
+            if (mountedRef.current && myId === requestIdRef.current) {
+                setResults(r);
+            }
+            return r;
+        }
+        catch (e) {
+            const err = e instanceof Error ? e : new Error(String(e));
+            if (mountedRef.current && myId === requestIdRef.current) {
+                setError(err);
+            }
+            throw err;
+        }
+        finally {
+            if (mountedRef.current && myId === requestIdRef.current) {
+                setLoading(false);
+            }
+        }
+    }, [client]);
+    const add = useCallback(async (content, metadata = {}) => {
+        // Bump the request id BEFORE awaiting so any in-flight ``search``
+        // started earlier loses the last-wins race and cannot wipe the
+        // memory we are about to prepend. Without this, a fast
+        // ``add()`` immediately after a slow ``search()`` would see the
+        // search resolve last and clobber the freshly-added entry.
+        const myId = ++requestIdRef.current;
+        const memory = (await client.add({ content, metadata }));
+        if (mountedRef.current && myId === requestIdRef.current) {
+            setResults((prev) => [memory, ...prev]);
+        }
+        return memory;
+    }, [client]);
+    const remove = useCallback(async (id) => {
+        const myId = ++requestIdRef.current;
+        await client.delete(id);
+        // Same last-wins guard as ``add`` — a slow concurrent ``search``
+        // could otherwise resolve after the delete and re-introduce the
+        // just-removed row into the rendered list.
+        if (mountedRef.current && myId === requestIdRef.current) {
+            setResults((prev) => prev.filter((r) => r?.id !== id));
+        }
+    }, [client]);
+    useEffect(() => {
+        if (options.initialQuery) {
+            void search(options.initialQuery, options.initialLimit);
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    return { results, loading, error, search, add, remove };
+}
+function resolveClient(opts) {
+    if (opts.client)
+        return opts.client;
+    const apiKey = opts.apiKey ?? process.env.NEXT_PUBLIC_GETMNEMO_API_KEY;
+    const workspaceId = opts.workspaceId ?? process.env.NEXT_PUBLIC_GETMNEMO_WORKSPACE_ID;
+    if (!apiKey || !workspaceId) {
+        throw new Error("useMnemo: missing apiKey/workspaceId. Note: client-side keys are public — prefer a server route in production.");
+    }
+    return new Mnemo({ apiKey, workspaceId });
+}
+//# sourceMappingURL=react.js.map

package/dist/react.js.map

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

package/dist/tools.d.ts

@@ -0,0 +1,37 @@
+import { Mnemo } from "getmnemo";
+import { tool } from "ai";
+/**
+ * Options for constructing a Mnemo toolset.
+ *
+ * Either pass `client` (a pre-built `Mnemo` instance) or `apiKey` +
+ * `workspaceId` and one will be created for you.
+ */
+export interface MnemoToolsOptions {
+    client?: Mnemo;
+    apiKey?: string;
+    workspaceId?: string;
+    /** Default `limit` passed to `search` when the model omits it. */
+    defaultLimit?: number;
+    /** Static metadata merged into every `add` call (e.g. `{ userId }`). */
+    metadata?: Record<string, unknown>;
+}
+export interface MnemoToolset {
+    memorySearch: ReturnType<typeof tool>;
+    memoryAdd: ReturnType<typeof tool>;
+}
+/**
+ * Build a pair of Vercel AI SDK tools backed by Mnemo.
+ *
+ * Drop the returned object into `streamText({ tools })` or
+ * `generateText({ tools })` and the model can search and write
+ * persistent memory.
+ */
+export declare function createMnemoTools(options?: MnemoToolsOptions): MnemoToolset;
+/**
+ * Pre-built default toolset using `GETMNEMO_API_KEY` and
+ * `GETMNEMO_WORKSPACE_ID` from `process.env`.
+ *
+ * Lazy — the client isn't constructed until a tool actually runs.
+ */
+export declare const getmnemoTools: MnemoToolset;
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAG1B;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,KAAK,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE,UAAU,CAAC,OAAO,IAAI,CAAC,CAAC;IACtC,SAAS,EAAE,UAAU,CAAC,OAAO,IAAI,CAAC,CAAC;CACpC;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,GAAE,iBAAsB,GAC9B,YAAY,CA8Dd;AAED;;;;;GAKG;AACH,eAAO,MAAM,aAAa,EAAE,YAMxB,CAAC"}

package/dist/tools.js

@@ -0,0 +1,90 @@
+import { Mnemo } from "getmnemo";
+import { tool } from "ai";
+import { z } from "zod";
+/**
+ * Build a pair of Vercel AI SDK tools backed by Mnemo.
+ *
+ * Drop the returned object into `streamText({ tools })` or
+ * `generateText({ tools })` and the model can search and write
+ * persistent memory.
+ */
+export function createMnemoTools(options = {}) {
+    const client = resolveClient(options);
+    const defaultLimit = options.defaultLimit ?? 5;
+    const baseMetadata = options.metadata ?? {};
+    const memorySearch = tool({
+        description: "Search the user's long-term memory for facts, preferences, or past conversations relevant to the current query. Returns the most relevant snippets.",
+        // .strict() emits additionalProperties:false so providers that honour
+        // strict JSON schema (OpenAI, Anthropic) reject hallucinated keys
+        // instead of silently dropping them at parse time.
+        parameters: z
+            .object({
+            query: z
+                .string()
+                .min(1)
+                .describe("Natural-language query describing what to recall."),
+            limit: z
+                .number()
+                .int()
+                .positive()
+                .max(50)
+                .optional()
+                .describe("Max number of memories to return."),
+        }),
+        execute: async ({ query, limit }) => {
+            // Clamp the limit defensively — the schema constrains the model,
+            // but a non-conforming provider response could still smuggle a
+            // huge value through and blow the context window.
+            const requested = limit ?? defaultLimit;
+            const safeLimit = Math.min(50, Math.max(1, Math.floor(requested)));
+            const results = await client.search({ query, limit: safeLimit });
+            return { results };
+        },
+    });
+    const memoryAdd = tool({
+        description: "Save a new fact, preference, or noteworthy detail about the user to long-term memory. Use sparingly — only for information worth remembering across sessions.",
+        parameters: z
+            .object({
+            content: z
+                .string()
+                .min(1)
+                .describe("The fact or note to remember, written in plain text."),
+            metadata: z
+                .record(z.unknown())
+                .optional()
+                .describe("Optional structured tags (e.g. { topic, source })."),
+        }),
+        execute: async ({ content, metadata }) => {
+            // Model-supplied metadata is merged FIRST so trusted baseMetadata
+            // (e.g. userId, workspaceId) cannot be overwritten by prompt injection.
+            const merged = { ...(metadata ?? {}), ...baseMetadata };
+            const memory = await client.add({ content, metadata: merged });
+            return { memory };
+        },
+    });
+    return { memorySearch, memoryAdd };
+}
+/**
+ * Pre-built default toolset using `GETMNEMO_API_KEY` and
+ * `GETMNEMO_WORKSPACE_ID` from `process.env`.
+ *
+ * Lazy — the client isn't constructed until a tool actually runs.
+ */
+export const getmnemoTools = (() => {
+    let cached = null;
+    const get = () => (cached ??= createMnemoTools());
+    return new Proxy({}, {
+        get: (_target, prop) => get()[prop],
+    });
+})();
+function resolveClient(opts) {
+    if (opts.client)
+        return opts.client;
+    const apiKey = opts.apiKey ?? process.env.GETMNEMO_API_KEY;
+    const workspaceId = opts.workspaceId ?? process.env.GETMNEMO_WORKSPACE_ID;
+    if (!apiKey || !workspaceId) {
+        throw new Error("createMnemoTools: missing apiKey/workspaceId. Pass them explicitly or set GETMNEMO_API_KEY and GETMNEMO_WORKSPACE_ID.");
+    }
+    return new Mnemo({ apiKey, workspaceId });
+}
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

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

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "getmnemo-vercel-ai",
+  "version": "0.1.0",
+  "description": "Mnemo adapter for the Vercel AI SDK — drop-in tools for streamText / generateText / useChat.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "lint": "tsc --noEmit"
+  },
+  "keywords": [
+    "getmnemo",
+    "vercel-ai",
+    "ai-sdk",
+    "memory",
+    "rag",
+    "tools"
+  ],
+  "author": "Mnemo <founders@getmnemo.xyz>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ledgermem/getmnemo-vercel-ai.git"
+  },
+  "dependencies": {
+    "getmnemo": "^0.1.0",
+    "zod": "^3.23.0"
+  },
+  "peerDependencies": {
+    "@ai-sdk/react": "^1.0.0",
+    "ai": "^4.0.0",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@ai-sdk/react": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.2.14",
+    "ai": "^4.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=18.17.0"
+  },
+  "homepage": "https://getmnemo.xyz"
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export {
+  createMnemoTools,
+  getmnemoTools,
+  type MnemoToolsOptions,
+  type MnemoToolset,
+} from "./tools.js";

package/src/react.ts

@@ -0,0 +1,129 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { Mnemo } from "getmnemo";
+
+export interface UseMnemoOptions {
+  apiKey?: string;
+  workspaceId?: string;
+  client?: Mnemo;
+  /** Initial query to run on mount; pass `undefined` to skip. */
+  initialQuery?: string;
+  initialLimit?: number;
+}
+
+export interface UseMnemoResult<T = unknown> {
+  results: T[];
+  loading: boolean;
+  error: Error | null;
+  search: (query: string, limit?: number) => Promise<T[]>;
+  add: (content: string, metadata?: Record<string, unknown>) => Promise<T>;
+  remove: (id: string) => Promise<void>;
+}
+
+/**
+ * Tiny React hook for direct Mnemo access from client components.
+ *
+ * For tool-use inside `useChat`, prefer wiring `getmnemoTools` into the
+ * server route instead — this hook is for sidebars / memory inspectors.
+ */
+export function useMnemo<T = unknown>(
+  options: UseMnemoOptions = {},
+): UseMnemoResult<T> {
+  const [client] = useState(() => resolveClient(options));
+  const [results, setResults] = useState<T[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  // Last-wins guard: every search() bumps the counter and only the most
+  // recent call is allowed to write to state. Without this, two rapid
+  // searches let the slower one overwrite the fresher one (the classic
+  // "stale request wins" race), and unmounting mid-flight wrote state on
+  // a torn-down component.
+  const requestIdRef = useRef(0);
+  const mountedRef = useRef(true);
+  useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+
+  const search = useCallback(
+    async (query: string, limit = 5): Promise<T[]> => {
+      const myId = ++requestIdRef.current;
+      setLoading(true);
+      setError(null);
+      try {
+        const r = ((await client.search({ query, limit })).hits) as unknown as T[];
+        if (mountedRef.current && myId === requestIdRef.current) {
+          setResults(r);
+        }
+        return r;
+      } catch (e) {
+        const err = e instanceof Error ? e : new Error(String(e));
+        if (mountedRef.current && myId === requestIdRef.current) {
+          setError(err);
+        }
+        throw err;
+      } finally {
+        if (mountedRef.current && myId === requestIdRef.current) {
+          setLoading(false);
+        }
+      }
+    },
+    [client],
+  );
+
+  const add = useCallback(
+    async (content: string, metadata: Record<string, unknown> = {}) => {
+      // Bump the request id BEFORE awaiting so any in-flight ``search``
+      // started earlier loses the last-wins race and cannot wipe the
+      // memory we are about to prepend. Without this, a fast
+      // ``add()`` immediately after a slow ``search()`` would see the
+      // search resolve last and clobber the freshly-added entry.
+      const myId = ++requestIdRef.current;
+      const memory = (await client.add({ content, metadata })) as T;
+      if (mountedRef.current && myId === requestIdRef.current) {
+        setResults((prev) => [memory, ...prev]);
+      }
+      return memory;
+    },
+    [client],
+  );
+
+  const remove = useCallback(
+    async (id: string) => {
+      const myId = ++requestIdRef.current;
+      await client.delete(id);
+      // Same last-wins guard as ``add`` — a slow concurrent ``search``
+      // could otherwise resolve after the delete and re-introduce the
+      // just-removed row into the rendered list.
+      if (mountedRef.current && myId === requestIdRef.current) {
+        setResults((prev) =>
+          prev.filter((r) => (r as { id?: string })?.id !== id),
+        );
+      }
+    },
+    [client],
+  );
+
+  useEffect(() => {
+    if (options.initialQuery) {
+      void search(options.initialQuery, options.initialLimit);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  return { results, loading, error, search, add, remove };
+}
+
+function resolveClient(opts: UseMnemoOptions): Mnemo {
+  if (opts.client) return opts.client;
+  const apiKey = opts.apiKey ?? process.env.NEXT_PUBLIC_GETMNEMO_API_KEY;
+  const workspaceId =
+    opts.workspaceId ?? process.env.NEXT_PUBLIC_GETMNEMO_WORKSPACE_ID;
+  if (!apiKey || !workspaceId) {
+    throw new Error(
+      "useMnemo: missing apiKey/workspaceId. Note: client-side keys are public — prefer a server route in production.",
+    );
+  }
+  return new Mnemo({ apiKey, workspaceId });
+}

package/src/tools.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import { createMnemoTools } from "./tools.js";
+
+vi.mock("getmnemo", () => {
+  return {
+    Mnemo: vi.fn().mockImplementation(() => ({
+      search: vi
+        .fn()
+        .mockResolvedValue([{ id: "m1", content: "user likes oat milk" }]),
+      add: vi.fn().mockResolvedValue({ id: "m2", content: "stored" }),
+      update: vi.fn(),
+      delete: vi.fn(),
+      list: vi.fn(),
+    })),
+  };
+});
+
+describe("createMnemoTools", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("builds memorySearch and memoryAdd tools", () => {
+    const tools = createMnemoTools({ apiKey: "k", workspaceId: "w" });
+    expect(tools.memorySearch).toBeDefined();
+    expect(tools.memoryAdd).toBeDefined();
+  });
+
+  it("memorySearch.execute calls client.search with default limit", async () => {
+    const tools = createMnemoTools({
+      apiKey: "k",
+      workspaceId: "w",
+      defaultLimit: 7,
+    });
+    const out = await tools.memorySearch.execute!(
+      { query: "oat milk" },
+      { messages: [], toolCallId: "t1" },
+    );
+    expect(out).toEqual({
+      results: [{ id: "m1", content: "user likes oat milk" }],
+    });
+  });
+
+  it("memoryAdd.execute merges base metadata with per-call metadata", async () => {
+    const tools = createMnemoTools({
+      apiKey: "k",
+      workspaceId: "w",
+      metadata: { userId: "u1" },
+    });
+    const out = await tools.memoryAdd.execute!(
+      { content: "likes oat milk", metadata: { topic: "drinks" } },
+      { messages: [], toolCallId: "t2" },
+    );
+    expect(out).toEqual({ memory: { id: "m2", content: "stored" } });
+  });
+
+  it("throws if apiKey missing and env unset", () => {
+    const orig = process.env.GETMNEMO_API_KEY;
+    delete process.env.GETMNEMO_API_KEY;
+    expect(() => createMnemoTools({})).toThrow(/missing apiKey/);
+    if (orig) process.env.GETMNEMO_API_KEY = orig;
+  });
+});

package/src/tools.ts

@@ -0,0 +1,123 @@
+import { Mnemo } from "getmnemo";
+import { tool } from "ai";
+import { z } from "zod";
+
+/**
+ * Options for constructing a Mnemo toolset.
+ *
+ * Either pass `client` (a pre-built `Mnemo` instance) or `apiKey` +
+ * `workspaceId` and one will be created for you.
+ */
+export interface MnemoToolsOptions {
+  client?: Mnemo;
+  apiKey?: string;
+  workspaceId?: string;
+  /** Default `limit` passed to `search` when the model omits it. */
+  defaultLimit?: number;
+  /** Static metadata merged into every `add` call (e.g. `{ userId }`). */
+  metadata?: Record<string, unknown>;
+}
+
+export interface MnemoToolset {
+  memorySearch: ReturnType<typeof tool>;
+  memoryAdd: ReturnType<typeof tool>;
+}
+
+/**
+ * Build a pair of Vercel AI SDK tools backed by Mnemo.
+ *
+ * Drop the returned object into `streamText({ tools })` or
+ * `generateText({ tools })` and the model can search and write
+ * persistent memory.
+ */
+export function createMnemoTools(
+  options: MnemoToolsOptions = {},
+): MnemoToolset {
+  const client = resolveClient(options);
+  const defaultLimit = options.defaultLimit ?? 5;
+  const baseMetadata = options.metadata ?? {};
+
+  const memorySearch: any = tool({
+    description:
+      "Search the user's long-term memory for facts, preferences, or past conversations relevant to the current query. Returns the most relevant snippets.",
+    // .strict() emits additionalProperties:false so providers that honour
+    // strict JSON schema (OpenAI, Anthropic) reject hallucinated keys
+    // instead of silently dropping them at parse time.
+    parameters: z
+      .object({
+        query: z
+          .string()
+          .min(1)
+          .describe("Natural-language query describing what to recall."),
+        limit: z
+          .number()
+          .int()
+          .positive()
+          .max(50)
+          .optional()
+          .describe("Max number of memories to return."),
+      })
+      ,
+    execute: async ({ query, limit }) => {
+      // Clamp the limit defensively — the schema constrains the model,
+      // but a non-conforming provider response could still smuggle a
+      // huge value through and blow the context window.
+      const requested = limit ?? defaultLimit;
+      const safeLimit = Math.min(50, Math.max(1, Math.floor(requested)));
+      const results = await client.search({ query, limit: safeLimit });
+      return { results };
+    },
+  });
+
+  const memoryAdd: any = tool({
+    description:
+      "Save a new fact, preference, or noteworthy detail about the user to long-term memory. Use sparingly — only for information worth remembering across sessions.",
+    parameters: z
+      .object({
+        content: z
+          .string()
+          .min(1)
+          .describe("The fact or note to remember, written in plain text."),
+        metadata: z
+          .record(z.unknown())
+          .optional()
+          .describe("Optional structured tags (e.g. { topic, source })."),
+      })
+      ,
+    execute: async ({ content, metadata }) => {
+      // Model-supplied metadata is merged FIRST so trusted baseMetadata
+      // (e.g. userId, workspaceId) cannot be overwritten by prompt injection.
+      const merged = { ...(metadata ?? {}), ...baseMetadata };
+      const memory = await client.add({ content, metadata: merged });
+      return { memory };
+    },
+  });
+
+  return { memorySearch, memoryAdd };
+}
+
+/**
+ * Pre-built default toolset using `GETMNEMO_API_KEY` and
+ * `GETMNEMO_WORKSPACE_ID` from `process.env`.
+ *
+ * Lazy — the client isn't constructed until a tool actually runs.
+ */
+export const getmnemoTools: MnemoToolset = (() => {
+  let cached: MnemoToolset | null = null;
+  const get = () => (cached ??= createMnemoTools());
+  return new Proxy({} as MnemoToolset, {
+    get: (_target, prop: string) => get()[prop as keyof MnemoToolset],
+  });
+})();
+
+function resolveClient(opts: MnemoToolsOptions): Mnemo {
+  if (opts.client) return opts.client;
+  const apiKey = opts.apiKey ?? process.env.GETMNEMO_API_KEY;
+  const workspaceId = opts.workspaceId ?? process.env.GETMNEMO_WORKSPACE_ID;
+  if (!apiKey || !workspaceId) {
+    throw new Error(
+      "createMnemoTools: missing apiKey/workspaceId. Pass them explicitly or set GETMNEMO_API_KEY and GETMNEMO_WORKSPACE_ID.",
+    );
+  }
+  return new Mnemo({ apiKey, workspaceId });
+}