feat(tools): 7-tool parity and description refresh

packages/tools/package.json

@@ -8,6 +8,7 @@
     "dev": "tsdown --watch --ignore-watch .turbo",
     "check-types": "tsc --noEmit",
     "test": "vitest --testTimeout 100000",
+    "test:unit": "vitest run --testTimeout 100000 src/tools-shared.test.ts src/tool-operations.test.ts test/with-supermemory/unit.test.ts test/with-supermemory/conversation-conversion.test.ts test/mastra/unit.test.ts",
     "test:watch": "vitest --watch --testTimeout 100000"
   },
   "dependencies": {
@@ -16,7 +17,7 @@
     "ai": "^5.0.29",
     "lru-cache": "^11.2.6",
     "openai": "^4.104.0",
-    "supermemory": "^3.0.0-alpha.26",
+    "supermemory": "^4.25.4",
     "zod": "^4.1.5"
   },
   "devDependencies": {

packages/tools/src/ai-sdk.ts

@@ -52,16 +52,16 @@
 		}),
 		execute: async ({
 			informationToGet,
 			includeFullDocs = DEFAULT_VALUES.includeFullDocs,
 			limit = DEFAULT_VALUES.limit,
 		}) => {
 			try {
-				const response = await client.search.execute({
+				const response = await client.search({
 					q: informationToGet,
-					containerTags,
+					...(containerTags[0] ? { containerTag: containerTags[0] } : {}),
 					limit,
-					chunkThreshold: DEFAULT_VALUES.chunkThreshold,
-					includeFullDocs,
+					threshold: DEFAULT_VALUES.chunkThreshold,
+					searchMode: "hybrid",
 				})
 
 				return {
@@ -373,3 +373,4 @@
 }
 
 export { withSupermemory } from "./vercel"
+export { getContainerTags } from "./tools-shared"

packages/tools/src/claude-memory.test.ts

@@ -1,17 +1,18 @@
 import { beforeEach, describe, expect, it, vi } from "vitest"
 
 // Mock the Supermemory SDK so the Claude memory tool's `view`/`readFile` path
 // can be exercised deterministically without any network access. We only need
-// `search.execute` to return a single document with known multi-line content.
-const searchExecute = vi.fn()
+// `client.search()` to return a single document with known multi-line content.
+const searchMock = vi.fn()
 const addMock = vi.fn()
 
 vi.mock("supermemory", () => {
 	return {
 		default: class MockSupermemory {
-			search = { execute: searchExecute }
+			search = searchMock
 			add = addMock
 			memories = { forget: vi.fn() }
+			documents = { delete: vi.fn() }
 		},
 	}
 })
@@ -23,18 +24,18 @@
 const FILE_CONTENT = "line1\nline2\nline3\nline4\nline5"
 
 function mockDocument(content: string) {
-	// `readFile` matches by `documentId === normalizePathToCustomId(path)`.
+	// `readFile` matches by `id === normalizePathToCustomId(path)`.
 	// normalizePathToCustomId("/memories/notes.txt") -> "memories_notes_txt"
-	searchExecute.mockResolvedValue({
-		results: [{ documentId: "memories_notes_txt", content }],
+	searchMock.mockResolvedValue({
+		results: [{ id: "memories_notes_txt", chunk: content }],
 	})
 }
 
 describe("ClaudeMemoryTool view_range", () => {
 	let tool: ClaudeMemoryTool
 
 	beforeEach(() => {
-		searchExecute.mockReset()
+		searchMock.mockReset()
 		mockDocument(FILE_CONTENT)
 		tool = new ClaudeMemoryTool("test-api-key")
 	})
@@ -89,16 +90,16 @@
 	let tool: ClaudeMemoryTool
 
 	beforeEach(() => {
-		searchExecute.mockReset()
+		searchMock.mockReset()
 		addMock.mockReset()
 		tool = new ClaudeMemoryTool("test-api-key")
 	})
 
 	it("view finds the exact file even when a neighbour ranks first", async () => {
-		searchExecute.mockResolvedValue({
+		searchMock.mockResolvedValue({
 			results: [
-				{ documentId: "memories_notes_backup_txt", content: "backup stuff" },
-				{ documentId: "memories_notes_txt", content: FILE_CONTENT },
+				{ id: "memories_notes_backup_txt", chunk: "backup stuff" },
+				{ id: "memories_notes_txt", chunk: FILE_CONTENT },
 			],
 		})
 
@@ -115,9 +116,9 @@
 	it("view reports not-found instead of returning a different file", async () => {
 		// Semantic search can surface a similarly-named file; that must not
 		// be served as the requested one.
-		searchExecute.mockResolvedValue({
+		searchMock.mockResolvedValue({
 			results: [
-				{ documentId: "memories_notes_backup_txt", content: "backup stuff" },
+				{ id: "memories_notes_backup_txt", chunk: "backup stuff" },
 			],
 		})
 
@@ -131,9 +132,9 @@
 	})
 
 	it("str_replace refuses to modify a different file than requested", async () => {
-		searchExecute.mockResolvedValue({
+		searchMock.mockResolvedValue({
 			results: [
-				{ documentId: "memories_notes_backup_txt", content: "backup stuff" },
+				{ id: "memories_notes_backup_txt", chunk: "backup stuff" },
 			],
 		})
 
@@ -153,31 +154,28 @@
 	let tool: ClaudeMemoryTool
 
 	beforeEach(() => {
-		searchExecute.mockReset()
+		searchMock.mockReset()
 		addMock.mockReset()
-		searchExecute.mockResolvedValue({
-			results: [{ documentId: "memories_notes_txt", content: FILE_CONTENT }],
+		searchMock.mockResolvedValue({
+			results: [{ id: "memories_notes_txt", chunk: FILE_CONTENT }],
 		})
 		tool = new ClaudeMemoryTool("test-api-key")
 	})
 
-	it.each([
-		"$&",
-		"$'",
-		"$`",
-		"$$",
-	])("stores %s literally instead of expanding it as a replacement pattern", async (dollarSequence) => {
-		const result = await tool.handleCommand({
-			command: "str_replace",
-			path: FILE_PATH,
-			old_str: "line3",
-			new_str: `price is ${dollarSequence} today`,
-		})
-
-		expect(result.success).toBe(true)
-		expect(addMock).toHaveBeenCalledTimes(1)
-		const stored = addMock.mock.calls[0]?.[0]?.content as string
-		expect(stored).toContain(`price is ${dollarSequence} today`)
-		expect(stored).not.toContain("line3")
-	})
+	it.each(["$&", "$'", "$`", "$$"])(
+		"stores %s literally instead of expanding it as a replacement pattern",
+		async (dollarSequence) => {
+			const result = await tool.handleCommand({
+				command: "str_replace",
+				path: FILE_PATH,
+				old_str: "line3",
+				new_str: `price is ${dollarSequence} today`,
+			})
+
+			expect(result.success).toBe(true)
+			expect(addMock).toHaveBeenCalledTimes(1)
+			const stored = addMock.mock.calls[0]?.[0]?.content as string
+			expect(stored).toContain(`price is ${dollarSequence} today`)
+		},
+	)
 })

packages/tools/src/claude-memory.ts

@@ -140,7 +140,7 @@
 				default:
 					return {
 						success: false,
 						error: `Unknown command: ${(command as any).command}`,
 					}
 			}
 		} catch (error) {
@@ -194,11 +194,13 @@
 	private async listDirectory(dirPath: string): Promise<MemoryResponse> {
 		try {
 			// Search for all memory files
-			const response = await this.client.search.execute({
+			const response = await this.client.search({
 				q: "*", // Search for all
-				containerTags: this.containerTags,
+				...(this.containerTags[0]
+					? { containerTag: this.containerTags[0] }
+					: {}),
 				limit: 100, // Get many files (max allowed)
-				includeFullDocs: false,
+				searchMode: "hybrid",
 			})
 
 			if (!response.results) {
@@ -571,36 +573,48 @@
 	 */
 	private async getFileDocument(filePath: string): Promise<{
 		success: boolean
 		document?: any
 		error?: string
 	}> {
 		try {
 			const normalizedId = this.normalizePathToCustomId(filePath)
 
-			const response = await this.client.search.execute({
+			const response = await this.client.search({
 				q: normalizedId,
-				containerTags: this.containerTags,
+				...(this.containerTags[0]
+					? { containerTag: this.containerTags[0] }
+					: {}),
 				limit: 5,
-				includeFullDocs: true,
+				searchMode: "hybrid",
 			})
 
 			// Only accept the exact customId match. Falling back to the top
 			// semantic hit would let callers read — and worse, modify or
 			// delete — a different file than the one they asked for.
-			const document = response.results?.find(
-				(r) => r.documentId === normalizedId,
+			const match = response.results?.find(
+				(r) =>
+					r.id === normalizedId ||
+					r.documents?.some((d) => d.id === normalizedId),
 			)
 
-			if (!document) {
+			if (!match) {
 				return {
 					success: false,
 					error: `File not found: ${filePath}`,
 				}
 			}
 
+			const content = match.chunk || match.memory || ""
+			const documentId = match.documents?.[0]?.id ?? match.id
+
 			return {
 				success: true,
-				document,
+				document: {
+					documentId,
+					content,
+					raw: content,
+					metadata: match.metadata,
+				},
 			}
 		} catch (error) {
 			return {

packages/tools/src/index.ts

@@ -3,3 +3,10 @@ export type { SupermemoryToolsConfig } from "./types"
 export type { OpenAIMiddlewareOptions } from "./openai"
 
 export type { SupermemoryVoltAgent } from "./voltagent"
+
+export {
+	TOOL_DESCRIPTIONS,
+	PARAMETER_DESCRIPTIONS,
+	DEFAULT_VALUES,
+	getContainerTags,
+} from "./tools-shared"

packages/tools/src/openai/tools.ts

@@ -14,14 +14,14 @@
  */
 export interface MemorySearchResult {
 	success: boolean
-	results?: Awaited<ReturnType<Supermemory["search"]["execute"]>>["results"]
+	results?: Awaited<ReturnType<Supermemory["search"]>>["results"]
 	count?: number
 	error?: string
 }
 
 export interface MemoryAddResult {
 	success: boolean
-	memory?: Awaited<ReturnType<Supermemory["memories"]["add"]>>
+	memory?: Awaited<ReturnType<Supermemory["add"]>>
 	error?: string
 }
 
@@ -31,7 +31,7 @@
 		static: string[]
 		dynamic: string[]
 	}
-	searchResults?: Awaited<ReturnType<Supermemory["search"]["execute"]>>
+	searchResults?: Awaited<ReturnType<Supermemory["search"]>>
 	error?: string
 }
 
@@ -240,7 +240,7 @@
 
 	return async function searchMemories({
 		informationToGet,
 		includeFullDocs = DEFAULT_VALUES.includeFullDocs,
 		limit = DEFAULT_VALUES.limit,
 	}: {
 		informationToGet: string
@@ -248,12 +248,12 @@
 		limit?: number
 	}): Promise<MemorySearchResult> {
 		try {
-			const response = await client.search.execute({
+			const response = await client.search({
 				q: informationToGet,
-				containerTags,
+				...(containerTags[0] ? { containerTag: containerTags[0] } : {}),
 				limit,
-				chunkThreshold: DEFAULT_VALUES.chunkThreshold,
-				includeFullDocs,
+				threshold: DEFAULT_VALUES.chunkThreshold,
+				searchMode: "hybrid",
 			})
 
 			return {

packages/tools/src/tool-operations.test.ts

@@ -4,13 +4,13 @@ import { beforeEach, describe, expect, it, vi } from "vitest"
 // executions can be verified deterministically without network access.
 const documentsDelete = vi.fn()
 const documentsList = vi.fn()
-const searchExecute = vi.fn()
+const searchMock = vi.fn()
 const clientAdd = vi.fn()
 
 vi.mock("supermemory", () => {
 	return {
 		default: class MockSupermemory {
-			search = { execute: searchExecute }
+			search = searchMock
 			add = clientAdd
 			documents = {
 				delete: documentsDelete,
@@ -40,7 +40,7 @@ beforeEach(() => {
 		memories: [{ id: "doc_1", title: "Doc one" }],
 		pagination: { currentPage: 1, totalItems: 1, totalPages: 1 },
 	})
-	searchExecute.mockReset()
+	searchMock.mockReset()
 	clientAdd.mockReset().mockResolvedValue({ id: "doc_new" })
 	vi.unstubAllGlobals()
 })
@@ -163,11 +163,11 @@ describe("ClaudeMemoryTool", () => {
 	const CUSTOM_ID = "memories_prefs_txt"
 
 	function mockFileDocument(content: string) {
-		searchExecute.mockResolvedValue({
+		searchMock.mockResolvedValue({
 			results: [
 				{
-					documentId: CUSTOM_ID,
-					content,
+					id: CUSTOM_ID,
+					chunk: content,
 					metadata: { file_path: FILE_PATH },
 				},
 			],