feat(tools): mass forget + bucket tools, and refresh the supermemory skill

packages/tools/README.md

@@ -669,20 +669,61 @@ interface WithSupermemoryOptions {
 
 ## Available Tools
 
-### Search Memories
+`supermemoryTools()` returns all of the following. Each is also exported individually — `searchMemoriesTool`, `memoryForgetMatchingTool`, and so on for the AI SDK, and `createSearchMemoriesFunction` / `createMemoryForgetMatchingTool` and friends for OpenAI function calling.
+
+### Search Memories (`searchMemories`)
 Searches through stored memories based on a query string.
 
 **Parameters:**
 - `informationToGet` (string): Terms to search for
 - `includeFullDocs` (boolean, optional): Whether to include full document content (default: true)
 - `limit` (number, optional): Maximum number of results (default: 10)
 
-### Add Memory
+### Add Memory (`addMemory`)
 Adds a new memory to the system.
 
 **Parameters:**
 - `memory` (string): The content to remember
 
+### Get Profile (`getProfile`)
+Returns the user's static (long-term) and dynamic (recent) memories, optionally with search results.
+
+**Parameters:**
+- `containerTag` (string, optional): Defaults to the configured container tag
+- `query` (string, optional): Also run a search and return the results
+
+### Get Profile Buckets (`getProfileBuckets`)
+Returns profile memories grouped into topical buckets (`preferences`, `goals`, `work`, …) instead of the whole profile — useful for keeping prompts small when only one slice matters.
+
+**Parameters:**
+- `containerTag` (string, optional): Defaults to the configured container tag
+- `buckets` (string[], optional): Bucket keys to return. Omit for every bucket configured for the user
+
+### Document List / Add / Delete (`documentList`, `documentAdd`, `documentDelete`)
+Browse, ingest, and delete source documents. `documentDelete` removes a document and its extracted memories.
+
+### Forget Memory (`memoryForget`)
+Soft-deletes one memory by ID or exact content match.
+
+**Parameters:**
+- `containerTag` (string, optional): Defaults to the configured container tag
+- `memoryId` (string): The memory to forget — or…
+- `memoryContent` (string): …its exact content
+- `reason` (string, optional): Recorded on the forgotten memory
+
+### Forget Matching (`memoryForgetMatching`)
+Forgets a whole topic in one call. Describe the target and matching memories are soft-deleted; pass explicit IDs to skip the search.
+
+**Parameters:**
+- `containerTag` (string, optional): Defaults to the configured container tag
+- `query` (string): What to forget, e.g. `"everything about Project Titan"` — or…
+- `memoryIds` (string[]): …the exact memories to forget
+- `dryRun` (boolean, optional): **Defaults to `true`** — the tool previews rather than deletes
+- `maxForget` (number, optional): Cap on how many memories one call may forget (default: 100)
+- `reason` (string, optional): Recorded on each forgotten memory
+
+The dry-run default is deliberate: a model gets a preview, not a deletion. The intended loop is preview → show the user the returned `memories` → call again with those `memoryIds` and `dryRun: false`. Applying with a `query` re-runs the semantic match, so it can select a different set than the preview showed.
+
 
 
 ## Claude Memory Tool

packages/tools/src/ai-sdk.ts

@@ -7,7 +7,11 @@ import {
 	TOOL_DESCRIPTIONS,
 	getContainerTags,
 } from "./tools-shared"
-import { forgetMemoryRequest } from "./shared/forget-memory"
+import {
+	forgetMatchingRequest,
+	forgetMemoryRequest,
+} from "./shared/forget-memory"
+import { profileBucketsRequest } from "./shared/profile-buckets"
 import type { SupermemoryToolsConfig } from "./types"
 
 // Export individual tool creators
@@ -354,6 +358,130 @@ export const memoryForgetTool = (
 	})
 }
 
+export const memoryForgetMatchingTool = (
+	apiKey: string,
+	config?: SupermemoryToolsConfig,
+) => {
+	const containerTags = getContainerTags(config)
+
+	return tool({
+		description: TOOL_DESCRIPTIONS.memoryForgetMatching,
+		inputSchema: z.object({
+			containerTag: z
+				.string()
+				.optional()
+				.describe(PARAMETER_DESCRIPTIONS.containerTag),
+			query: z.string().optional().describe(PARAMETER_DESCRIPTIONS.forgetQuery),
+			memoryIds: z
+				.array(z.string())
+				.optional()
+				.describe(PARAMETER_DESCRIPTIONS.forgetMemoryIds),
+			dryRun: z
+				.boolean()
+				.optional()
+				.default(DEFAULT_VALUES.forgetDryRun)
+				.describe(PARAMETER_DESCRIPTIONS.forgetDryRun),
+			maxForget: z.coerce
+				.number()
+				.optional()
+				.default(DEFAULT_VALUES.forgetMaxForget)
+				.describe(PARAMETER_DESCRIPTIONS.forgetMaxForget),
+			reason: z.string().optional().describe(PARAMETER_DESCRIPTIONS.reason),
+		}),
+		execute: async ({
+			containerTag,
+			query,
+			memoryIds,
+			dryRun = DEFAULT_VALUES.forgetDryRun,
+			maxForget = DEFAULT_VALUES.forgetMaxForget,
+			reason,
+		}) => {
+			try {
+				if (!query && !memoryIds?.length) {
+					return {
+						success: false,
+						error: "Either query or memoryIds must be provided",
+					}
+				}
+
+				const tag = containerTag || containerTags[0]
+
+				const result = await forgetMatchingRequest(
+					apiKey,
+					{
+						containerTag: tag as string,
+						dryRun,
+						maxForget,
+						...(query && { query }),
+						...(memoryIds?.length && { ids: memoryIds }),
+						...(reason && { reason }),
+					},
+					config?.baseUrl,
+				)
+
+				return {
+					success: true,
+					dryRun: result.dryRun,
+					count: result.count,
+					summary: result.summary,
+					memories: result.candidates ?? result.forgotten ?? [],
+					forgetBatchId: result.forgetBatchId,
+				}
+			} catch (error) {
+				return {
+					success: false,
+					error: error instanceof Error ? error.message : "Unknown error",
+				}
+			}
+		},
+	})
+}
+
+export const getProfileBucketsTool = (
+	apiKey: string,
+	config?: SupermemoryToolsConfig,
+) => {
+	const containerTags = getContainerTags(config)
+
+	return tool({
+		description: TOOL_DESCRIPTIONS.getProfileBuckets,
+		inputSchema: z.object({
+			containerTag: z
+				.string()
+				.optional()
+				.describe(PARAMETER_DESCRIPTIONS.containerTag),
+			buckets: z
+				.array(z.string())
+				.optional()
+				.describe(PARAMETER_DESCRIPTIONS.bucketKeys),
+		}),
+		execute: async ({ containerTag, buckets }) => {
+			try {
+				const tag = containerTag || containerTags[0]
+
+				const result = await profileBucketsRequest(
+					apiKey,
+					{
+						containerTag: tag as string,
+						...(buckets?.length && { buckets }),
+					},
+					config?.baseUrl,
+				)
+
+				return {
+					success: true,
+					buckets: result.buckets,
+				}
+			} catch (error) {
+				return {
+					success: false,
+					error: error instanceof Error ? error.message : "Unknown error",
+				}
+			}
+		},
+	})
+}
+
 /**
  * Create Supermemory tools for AI SDK
  */
@@ -365,10 +493,12 @@ export function supermemoryTools(
 		searchMemories: searchMemoriesTool(apiKey, config),
 		addMemory: addMemoryTool(apiKey, config),
 		getProfile: getProfileTool(apiKey, config),
+		getProfileBuckets: getProfileBucketsTool(apiKey, config),
 		documentList: documentListTool(apiKey, config),
 		documentDelete: documentDeleteTool(apiKey, config),
 		documentAdd: documentAddTool(apiKey, config),
 		memoryForget: memoryForgetTool(apiKey, config),
+		memoryForgetMatching: memoryForgetMatchingTool(apiKey, config),
 	}
 }